telegram-bot-control 0.5.1__tar.gz

telegram_bot_control-0.5.1/AUTHORS.md

@@ -0,0 +1,7 @@
+# Author
+
+Telegram Bot Control was created and is maintained by
+[Дмитрий Варг](https://github.com/olegoleg1111121).
+The project and original source code belong to its author.
+
+Third-party software keeps its respective authorship and licenses.

telegram_bot_control-0.5.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Дмитрий Варг
+
+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.

telegram_bot_control-0.5.1/MANIFEST.in

@@ -0,0 +1,16 @@
+include LICENSE README.md README.ru.md README.pypi.md THIRD_PARTY_NOTICES.md AUTHORS.md
+include requirements-dev.lock
+recursive-include src *.py
+recursive-include src/telegram_bot_control/web_assets *.html *.js *.css *.woff2 *.png *.svg *.txt
+recursive-include examples *.py *.ps1 *.json *.toml
+recursive-include scripts *.py *.ps1
+recursive-include tests *.py
+recursive-include docs *.md
+prune .git
+prune .local-tools
+prune .test-data
+prune .venv
+prune .pnpm-store
+prune desktop
+prune release
+global-exclude __pycache__ *.py[cod] *.sqlite3 *.sqlite3-wal *.sqlite3-shm *.db .env .env.* *.log

telegram_bot_control-0.5.1/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: telegram-bot-control
+Version: 0.5.1
+Summary: Embedded bot telemetry with desktop and optional authenticated web dashboards.
+Author: Дмитрий Варг
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/olegoleg1111121/telegram-bot-control
+Project-URL: Repository, https://github.com/olegoleg1111121/telegram-bot-control
+Project-URL: Documentation, https://github.com/olegoleg1111121/telegram-bot-control/blob/main/README.ru.md
+Project-URL: Issues, https://github.com/olegoleg1111121/telegram-bot-control/issues
+Project-URL: Changelog, https://github.com/olegoleg1111121/telegram-bot-control/blob/main/CHANGELOG.md
+Keywords: telegram,aiogram,monitoring,desktop,sqlite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psutil<8,>=7
+Provides-Extra: aiogram
+Requires-Dist: aiogram<4,>=3.20; extra == "aiogram"
+Provides-Extra: dev
+Requires-Dist: aiogram<4,>=3.20; extra == "dev"
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: pytest-asyncio<2,>=0.25; extra == "dev"
+Requires-Dist: ruff<1,>=0.14; extra == "dev"
+Provides-Extra: release
+Requires-Dist: build<2,>=1.2; extra == "release"
+Requires-Dist: twine<7,>=6; extra == "release"
+Dynamic: license-file
+
+# Telegram Bot Control
+
+Monitoring and process control for existing aiogram bots. One owner, one Windows
+or Linux server, many bots. Includes an embedded Python SDK, an optional browser
+dashboard and a separately distributed desktop application.
+
+## Install
+
+For an aiogram bot:
+
+```sh
+python -m pip install "telegram-bot-control[aiogram]"
+```
+
+For the lightweight web dashboard or stdio/SSH reader:
+
+```sh
+python -m pip install telegram-bot-control
+```
+
+Requires Python 3.11+. The base package depends only on psutil. The wheel includes
+the web UI and local Latin/Cyrillic fonts; Node.js and Electron are not required
+for browser mode. Windows setup and Linux AppImage are distributed through
+[GitHub Releases](https://github.com/olegoleg1111121/telegram-bot-control/releases).
+
+## Connect your bot
+
+After creating your existing Bot and Dispatcher, add this inside your startup
+function, before polling:
+
+```python
+from telegram_bot_control import start
+
+monitor = start(
+    bot=bot,
+    dispatcher=dp,
+    data_dir="/srv/bot-control/data",  # choose your own absolute directory
+)
+dp.update.outer_middleware(monitor.middleware())
+
+await dp.start_polling(bot)
+```
+
+Use the same data directory for all connected bots and the dashboard. On Windows,
+an example is `data_dir=r"C:\BotControl\data"`. Keep your existing handlers,
+routers, environment loader and polling call. The SDK writes bounded batches to
+per-bot SQLite WAL files without opening a listening port in the bot.
+
+Start the optional browser dashboard:
+
+```sh
+tgbots web --port 8765 --data-dir /srv/bot-control/data
+```
+
+The terminal displays a loopback URL and a separate dashboard access key.
+For network access and Termux, see the
+[web dashboard guide](https://github.com/olegoleg1111121/telegram-bot-control/blob/main/docs/web-panel.ru.md).
+The default mode is local HTTP; use an HTTPS proxy or SSH tunnel for untrusted networks.
+
+## Features
+
+- Bot status, message/command/button counters and retained error history.
+- Existing Python logging and optional Loguru adapters, search and secret redaction.
+- CPU, RSS and thread history for each bot's Python process.
+- Explicit launch profiles: arguments, working directory, preparation steps and optional env-file.
+- Start, graceful stop, restart and bounded on-failure automatic restarts.
+- Detailed startup stderr/stdout, including failures before SDK initialization.
+- Russian/English interfaces and configurable retention.
+
+Optional integration with an already configured logger:
+
+```python
+monitor.capture_logs()  # standard logging; existing handlers are preserved
+# For Loguru, use logger.add(monitor.loguru_sink, level="INFO") instead.
+```
+
+This is an early preview for a single trusted owner. Process control verifies PID,
+creation time and owner. Multiple bots sharing one Python process share resource
+measurements and cannot be stopped independently. It does not install an OS boot
+service or import historical log files.
+
+Created by [Дмитрий Варг](https://github.com/olegoleg1111121). MIT license.
+
+[Source and documentation](https://github.com/olegoleg1111121/telegram-bot-control)
+· [Russian walkthrough](https://github.com/olegoleg1111121/telegram-bot-control/blob/main/docs/getting-started.ru.md)
+· [Issues](https://github.com/olegoleg1111121/telegram-bot-control/issues)

telegram_bot_control-0.5.1/README.md

@@ -0,0 +1,232 @@
+<div align="center">
+  <img src="desktop/assets/icon.svg" width="88" alt="Telegram Bot Control icon">
+  <h1>Telegram Bot Control</h1>
+  <p>Desktop monitoring and process control for aiogram bots.</p>
+  <p>Python · aiogram · Electron · React · TypeScript · SQLite</p>
+  <p><a href="README.ru.md">Русская инструкция</a> · <a href="docs/process-control.md">Launch profiles</a> · <a href="docs/case-study.md">Engineering notes</a> · <a href="docs/releasing.md">Release guide</a></p>
+</div>
+
+**v0.5.1 · Preview · MIT**
+
+Startup failures now show retained command stdout/stderr, including errors before
+SDK initialization, with secret redaction and bounded output history.
+
+New in 0.5.0: existing logging/Loguru streams, per-process CPU/RSS history, bounded
+on-failure restarts and a guided existing-project connector. Available in both
+desktop and web modes. [Diagnostics](docs/diagnostics.ru.md) · [Project wizard](docs/project-wizard.ru.md).
+
+One owner, one server, many bots. Connect a small Python SDK to existing aiogram
+applications, inspect activity and exceptions, and control their processes from a
+dark desktop interface. Local transport uses SQLite WAL and standard input/output.
+Remote Linux access uses the same bridge over SSH.
+
+An optional authenticated web dashboard serves the same interface on a chosen port,
+including headless hosts and Termux. It is disabled by default. Run
+`tgbots web --port 8765 --data-dir /srv/bot-control/data`, or enable it under desktop
+Settings → Web dashboard. The terminal/settings show a separate browser access key.
+[Web/Termux guide](docs/web-panel.ru.md).
+
+[Measured distribution size and packaging changes](docs/size-report.md).
+
+<img src="docs/assets/overview.png" alt="Server overview with activity charts and three demonstration bots" width="1200">
+
+_All screenshots use synthetic demo data and anonymous server labels._
+
+## Install a release
+
+Download desktop installers or the portable Windows ZIP from
+[GitHub Releases](https://github.com/olegoleg1111121/telegram-bot-control/releases).
+The Python wheel includes the web dashboard and can be installed without Node.js:
+
+```sh
+python -m pip install "telegram-bot-control[aiogram] @ https://github.com/olegoleg1111121/telegram-bot-control/releases/download/v0.5.1/telegram_bot_control-0.5.1-py3-none-any.whl"
+```
+
+A PyPI Trusted Publishing workflow is included. Once the PyPI project is published,
+the equivalent command is `python -m pip install "telegram-bot-control[aiogram]"`.
+[PyPI setup and publication](docs/pypi.ru.md).
+
+## What it does
+
+- Registers bots automatically and keeps their history across restarts.
+- Shows heartbeat state separately from user activity.
+- Counts messages, commands, callbacks and distinct users over a selected range.
+- Groups handler exceptions and expands sanitized technical details.
+- Starts, gracefully stops and restarts bots with their configured launch profile.
+- Preserves arguments, working directory, preparation steps and environment-file paths.
+- Checks process identity using PID and creation time before termination.
+- Keeps collecting while the desktop window is closed.
+- Supports Russian and English, time zones and configurable retention.
+- Includes a first-run guide, close-to-tray behavior and Windows installation shortcuts.
+- Optional browser access, responsive phone layout and locally bundled Inter fonts.
+
+[First-run walkthrough (Russian)](docs/getting-started.ru.md). Reopen the in-app guide
+from the sidebar or system tray. Closing the window hides it; use the tray menu to quit.
+
+<details>
+<summary>First-run guide</summary>
+
+<img src="docs/assets/onboarding.png" alt="Russian first-run guide with connection, aiogram integration and system tray instructions" width="1100">
+
+</details>
+
+## Try it locally
+
+Requirements: **Python 3.11+**, **Node.js 24**, and **pnpm 11.25.0**.
+Run these commands from a source checkout or extracted source archive:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install -e '.[dev]'
+pnpm install --dir desktop --frozen-lockfile
+pnpm --dir desktop run build
+```
+
+For Linux, use `.venv/bin/python` and `.venv/bin/tgbots`.
+Install pnpm with `npm install --global pnpm@11.25.0` if needed.
+
+Start an explicit offline analytics demo in one terminal:
+
+```powershell
+.\.venv\Scripts\tgbots.exe demo --bots 3 --data-dir .bot-control
+```
+
+Open the desktop from another terminal in the same folder:
+
+```powershell
+.\.venv\Scripts\tgbots.exe open --data-dir .bot-control
+```
+
+The demo uses real aiogram dispatchers with a network-free session. It generates
+messages, commands, button events and a controlled exception. No Telegram account
+or bot token is required.
+
+For the independent Start/Stop/Restart walkthrough, use the complex fixture:
+
+```powershell
+.\.venv\Scripts\python.exe scripts/control_fixture.py --data-dir .bot-control/workflow --project-dir '.test-data/Workflow Bot'
+.\.venv\Scripts\tgbots.exe open --data-dir .bot-control/workflow
+```
+
+Select the bot card and press **Start**. This fixture includes nested routers,
+FSM, a preparation command, arguments with spaces and a separate environment file.
+
+## Connect an existing bot
+
+Install this Python package into the bot's environment, then add:
+
+```python
+from telegram_bot_control import start
+
+monitor = start(
+    bot=bot,
+    dispatcher=dp,
+    data_dir=r"C:\BotControl\data",
+    actions={"catalog:open": "catalog.open"},
+)
+dp.update.outer_middleware(monitor.middleware())
+
+await dp.start_polling(bot)
+```
+
+All bots and the desktop must use the same local data directory. On Linux, choose
+an absolute path such as `/srv/bot-control`. The import performs no registration
+or network request; recording begins during aiogram startup.
+
+For webhook or custom runtimes, connect the dispatcher lifecycle and provide a
+`shutdown` callback. See the [Russian integration guide](README.ru.md) and
+[process-control reference](docs/process-control.md).
+
+## Process control and complex launches
+
+The SDK records the actual Python arguments and working directory. Configure an
+explicit profile for wrappers, preparation or tools such as PowerShell:
+
+```json
+{
+  "command": ["/opt/bots/.venv/bin/python", "-u", "-m", "shop_bot", "--config", "config/prod config.json"],
+  "cwd": "/opt/bots/shop",
+  "pre_start": [["/opt/bots/.venv/bin/python", "prepare.py"]],
+  "env_file": "/opt/bots/shop/.env",
+  "environment": {"BOT_MODE": "production"},
+  "required_env": ["BOT_TOKEN"]
+}
+```
+
+Arguments are passed with `shell=False`. Secrets belong in an environment file or
+an environment-variable reference. A failed preflight keeps an existing bot running.
+Graceful shutdown is attempted first; forced termination requires a separate action.
+
+<details>
+<summary>Process controls and grouped exceptions</summary>
+
+<img src="docs/assets/processes.png" alt="Start, Stop and Restart controls exercised on an offline aiogram workflow" width="1100">
+<img src="docs/assets/errors.png" alt="Grouped demonstration exceptions with expandable details" width="1100">
+
+</details>
+
+## Architecture
+
+```mermaid
+flowchart LR
+  SDK[aiogram bot + SDK] -->|events and heartbeat|DB[(Per-bot SQLite WAL)]
+  DB -->|addressed stop request|SDK
+  UI[Electron desktop] <-->|JSON lines over stdio or SSH|Bridge[Python bridge]
+  Bridge -->|queries and settings|DB
+  Bridge -->|launch profile|Runner[Detached launcher]
+  Runner -->|argv, cwd, environment|SDK
+```
+
+The reader is a child process of the desktop. Each bot owns its recorder and file,
+so collection continues independently of the window. SSH runs the reader on the
+server; SQLite is always accessed on that machine's local disk.
+
+[Design decisions](docs/case-study.md) · [Implementation overview](docs/architecture.md)
+
+## Verification
+
+```powershell
+.\.venv\Scripts\python.exe -m pytest -q
+pnpm --dir desktop run test
+pnpm --dir desktop run format:check
+pnpm --dir desktop run build
+.\.venv\Scripts\python.exe scripts/release_check.py
+```
+
+The suite covers genuine aiogram handling, distinct-user aggregation, deduplication,
+retention, backups, process identity, concurrent starts, complex launch profiles,
+PowerShell, failed preparation and graceful/forced shutdown. Electron smoke tests
+press the real controls and inspect the resulting state.
+
+[Recorded validation and remaining platform checks](docs/validation.md).
+Windows was exercised locally. GitHub Actions are configured for Windows and Linux;
+hosted CI results will be available after this repository is published.
+
+## Release and installation
+
+A release contains the Python wheel, Python source distribution, full source archive,
+Windows installer, portable Windows folder archive and SHA256 checksums. The tag
+workflow also builds a Linux AppImage. Python is installed separately and selected
+in desktop connection settings.
+
+The desktop binaries are unsigned preview builds. Review the release notes and
+verify checksums before use. Local preparation and later GitHub publication are
+separate steps: [release guide](docs/releasing.md).
+
+## Scope
+
+- One owner and one server, with separate OS processes for independently controlled bots.
+- No Docker or multi-user account/role system. Web access is owner-only.
+- No systemd, Windows-service or external-supervisor adapter yet.
+- Raw updates, message bodies and full callback payloads are excluded from telemetry.
+- User identifiers are pseudonymized per bot for distinct counts.
+- Abrupt shutdown or storage failure can lose queued telemetry; loss counters are exposed.
+- Retention defaults: statistics 365 days, errors 30 days, diagnostics 7 days.
+
+[Security model](SECURITY.md) · [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md)
+
+## Author and license
+
+Created and maintained by the repository owner. Original project code and assets
+are available under the [MIT license](LICENSE). Third-party components retain their
+respective licenses; see [notices](THIRD_PARTY_NOTICES.md).

telegram_bot_control-0.5.1/README.pypi.md

@@ -0,0 +1,86 @@
+# Telegram Bot Control
+
+Monitoring and process control for existing aiogram bots. One owner, one Windows
+or Linux server, many bots. Includes an embedded Python SDK, an optional browser
+dashboard and a separately distributed desktop application.
+
+## Install
+
+For an aiogram bot:
+
+```sh
+python -m pip install "telegram-bot-control[aiogram]"
+```
+
+For the lightweight web dashboard or stdio/SSH reader:
+
+```sh
+python -m pip install telegram-bot-control
+```
+
+Requires Python 3.11+. The base package depends only on psutil. The wheel includes
+the web UI and local Latin/Cyrillic fonts; Node.js and Electron are not required
+for browser mode. Windows setup and Linux AppImage are distributed through
+[GitHub Releases](https://github.com/olegoleg1111121/telegram-bot-control/releases).
+
+## Connect your bot
+
+After creating your existing Bot and Dispatcher, add this inside your startup
+function, before polling:
+
+```python
+from telegram_bot_control import start
+
+monitor = start(
+    bot=bot,
+    dispatcher=dp,
+    data_dir="/srv/bot-control/data",  # choose your own absolute directory
+)
+dp.update.outer_middleware(monitor.middleware())
+
+await dp.start_polling(bot)
+```
+
+Use the same data directory for all connected bots and the dashboard. On Windows,
+an example is `data_dir=r"C:\BotControl\data"`. Keep your existing handlers,
+routers, environment loader and polling call. The SDK writes bounded batches to
+per-bot SQLite WAL files without opening a listening port in the bot.
+
+Start the optional browser dashboard:
+
+```sh
+tgbots web --port 8765 --data-dir /srv/bot-control/data
+```
+
+The terminal displays a loopback URL and a separate dashboard access key.
+For network access and Termux, see the
+[web dashboard guide](https://github.com/olegoleg1111121/telegram-bot-control/blob/main/docs/web-panel.ru.md).
+The default mode is local HTTP; use an HTTPS proxy or SSH tunnel for untrusted networks.
+
+## Features
+
+- Bot status, message/command/button counters and retained error history.
+- Existing Python logging and optional Loguru adapters, search and secret redaction.
+- CPU, RSS and thread history for each bot's Python process.
+- Explicit launch profiles: arguments, working directory, preparation steps and optional env-file.
+- Start, graceful stop, restart and bounded on-failure automatic restarts.
+- Detailed startup stderr/stdout, including failures before SDK initialization.
+- Russian/English interfaces and configurable retention.
+
+Optional integration with an already configured logger:
+
+```python
+monitor.capture_logs()  # standard logging; existing handlers are preserved
+# For Loguru, use logger.add(monitor.loguru_sink, level="INFO") instead.
+```
+
+This is an early preview for a single trusted owner. Process control verifies PID,
+creation time and owner. Multiple bots sharing one Python process share resource
+measurements and cannot be stopped independently. It does not install an OS boot
+service or import historical log files.
+
+Created by [Дмитрий Варг](https://github.com/olegoleg1111121). MIT license.
+
+[Source and documentation](https://github.com/olegoleg1111121/telegram-bot-control)
+· [Russian walkthrough](https://github.com/olegoleg1111121/telegram-bot-control/blob/main/docs/getting-started.ru.md)
+· [Issues](https://github.com/olegoleg1111121/telegram-bot-control/issues)