telemux 1.0.1__tar.gz

telemux-1.0.1/CHANGELOG.md

@@ -0,0 +1,171 @@
+# Changelog
+
+All notable changes to TeleMux will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased] - v1.0.0
+
+### Planned
+- Production testing completion (7+ days with 3+ users)
+- Performance benchmarking validation (1000+ messages)
+- Security audit execution
+- Public release announcement
+
+## [0.9.1] - 2025-11-10
+
+### Added
+- **Comprehensive test suite** (56 passing tests)
+  - Unit tests for message parsing, agent lookup, state management
+  - Integration tests with mocked Telegram API
+  - Security tests for command injection prevention
+  - Test coverage >70% of critical paths
+- **Performance benchmarking tool** (`benchmark.sh`)
+  - Configurable message count and delays
+  - Success rate validation (95%+ threshold)
+  - Comprehensive logging and metrics
+- **Security audit checklist** (`SECURITY_AUDIT.md`)
+  - 50+ checks across 13 security categories
+  - Credential management validation
+  - Command injection prevention tests
+- **Documentation improvements**
+  - Organized docs into `docs/` folder
+  - Added emoji-free style guide
+  - Created `.env.example` template
+  - Fixed config path errors in README (9 instances)
+- **GitHub Actions CI/CD**
+  - Automated testing on push/PR
+  - Multi-version Python support (3.8-3.12)
+  - Code linting and shellcheck
+  - Coverage reporting
+
+### Fixed
+- README.md config paths (`~/.telegram_config` → `~/.telemux/telegram_config`)
+- Shell function installation instructions now match INSTALL.sh
+- Missing v0.9.1 command aliases in documentation
+
+### Changed
+- Simplified shell function installation (source from single file)
+- Cleaned up 7 development artifact files
+
+## [0.9.0] - 2025-11-09
+
+### Added
+- **Log rotation system** (`cleanup-logs.sh`)
+  - 10MB size limit with automatic archiving
+  - Archives to `message_queue/archive/YYYY-MM/`
+  - Auto-cleanup of archives older than 6 months
+  - Optional cron job installation
+  - New command: `tg-cleanup`
+- **Health check diagnostics** (`tg-doctor`)
+  - Validates tmux, Python, dependencies
+  - Checks config file format and permissions
+  - Tests bot connection
+  - Validates chat ID format
+  - Shows message queue statistics
+- **Enhanced error handling**
+  - Retry logic with exponential backoff (3 attempts)
+  - Separate timeout and connection error handling
+  - Better error messages for common failures
+  - Graceful degradation when Telegram unreachable
+  - Separate error log file (`telegram_errors.log`)
+- **Dependency management**
+  - Created `requirements.txt` with pinned versions
+  - Updated INSTALL.sh to check/install dependencies
+  - Python version detection
+  - Graceful handling when pip3 not available
+- **Enhanced logging**
+  - Configurable log levels (DEBUG/INFO/WARNING/ERROR)
+  - `TELEMUX_LOG_LEVEL` environment variable
+  - Separate error log file
+  - Multiple handlers with different levels
+- **Migration and uninstall tools**
+  - `MIGRATE.sh` - Migrate from legacy `.team_mux` paths
+  - `UNINSTALL.sh` - Complete removal with backup option
+  - `UPDATE.sh` - Upgrade existing installations
+
+### Fixed
+- Documentation inconsistencies (function names, branding)
+- Path references (updated `.team_mux` → `.telemux`)
+- All TODOs resolved
+
+### Changed
+- Environment variables: `TELEGRAM_*` → `TELEMUX_TG_*`
+- Project renamed from "Team Mux" to "TeleMux"
+- Moved from `~/.team_mux/` to `~/.telemux/`
+
+## [0.1.0] - 2025-11-09
+
+### Added
+- Initial release of TeleMux bidirectional Telegram bridge
+- **Core Features**
+  - `tg_alert()` - Send one-way notifications to Telegram
+  - `tg_agent()` - Bidirectional agent messaging
+  - `tg_done()` - Alert when commands complete
+- **Listener Daemon**
+  - Python daemon with long-polling
+  - Runs 24/7 in dedicated tmux session
+  - Auto-recovery on restart
+  - State management for message tracking
+- **Message Queue System**
+  - Persistent logging of all messages
+  - Inbox files for each agent
+  - Audit trail for sent/received messages
+- **Clean API**
+  - Session name as message ID (simple format)
+  - Formatted delivery: `message`
+  - Proper tmux injection with sleep + Enter
+- **Control Commands**
+  - `tg-start` / `tg-stop` / `tg-restart`
+  - `tg-status` - Check listener status
+  - `tg-logs` - View logs
+  - `tg-attach` - Attach to listener session
+- **Components**
+  - `telegram_listener.py` - Main listener daemon
+  - `telegram_control.sh` - Control script
+  - `shell_functions.sh` - Shell integration
+  - `INSTALL.sh` - Automated installer
+- **Documentation**
+  - README.md - Complete user guide
+  - QUICKSTART.md - 5-minute setup
+  - CLAUDE.md - Technical documentation
+  - Example scripts (deployment, build, agent questions)
+
+### Requirements
+- tmux
+- Python 3.6+
+- curl
+- Telegram bot (via @BotFather)
+
+---
+
+## Future Enhancements
+
+### v1.1.0 (Planned)
+- Multiple chat support (group + personal DM)
+- Rich message formatting (markdown, buttons)
+- Message threading/conversations
+- Command shortcuts (/deploy, /status, etc.)
+- Fish shell support
+- Interactive setup wizard
+
+### v1.2.0 (Planned)
+- Web dashboard for message history
+- Agent status monitoring
+- Message analytics and insights
+- Performance optimizations
+
+### v2.0.0 (Planned - Multi-Platform)
+- WhatsApp integration (Twilio API)
+- Slack integration
+- Discord integration
+- Multi-user support
+- Permission system
+- Approval workflows
+
+---
+
+**Repository:** https://github.com/maarco/telemux
+**License:** MIT
+**Maintainer:** Marco (with Claude Code)

telemux-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Marco Almazan
+
+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.

telemux-1.0.1/MANIFEST.in

@@ -0,0 +1,15 @@
+# Include shell functions
+include telemux/shell_functions.sh
+
+# Include documentation
+include README.md
+include LICENSE
+include CHANGELOG.md
+
+# Include example scripts
+recursive-include examples *.sh
+
+# Exclude tests and development files
+exclude tests/*
+exclude .gitignore
+exclude .python-version

telemux-1.0.1/PKG-INFO

@@ -0,0 +1,479 @@
+Metadata-Version: 2.4
+Name: telemux
+Version: 1.0.1
+Summary: Bidirectional Telegram integration for tmux sessions - monitor commands and interact with agents
+Author-email: Marco Almazan <marco@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/malmazan/telemux
+Project-URL: Repository, https://github.com/malmazan/telemux
+Project-URL: Issues, https://github.com/malmazan/telemux/issues
+Keywords: telegram,tmux,notifications,monitoring,agent,automation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3.0.0,>=2.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.11.1; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: responses>=0.23.0; extra == "dev"
+Dynamic: license-file
+
+# TeleMux
+
+**Bidirectional Telegram integration for tmux sessions** - Monitor commands, interact with agents, and stay connected to your terminal from anywhere.
+
+## Features
+
+- **One-way notifications**: Send alerts to Telegram when commands complete
+- **Bidirectional communication**: Interact with tmux sessions via Telegram
+- **Agent support**: Create interactive agents that can receive replies
+- **Session routing**: Messages automatically delivered to the correct tmux session
+- **Daemon-based**: Runs as a background service in tmux
+- **Shell integration**: Simple shell functions for easy use
+- **Secure**: Configuration files are automatically protected (chmod 600)
+
+## Installation
+
+### Via pip (Recommended)
+
+```bash
+# Install the package
+pip install telemux
+
+# Run the interactive installer
+telemux install
+
+# Start the listener daemon
+telemux start
+```
+
+### From source
+
+```bash
+# Clone the repository
+git clone https://github.com/malmazan/telemux.git
+cd telemux
+
+# Install in development mode
+pip install -e .
+
+# Run the installer
+telemux install
+```
+
+## Quick Start
+
+### 1. Create a Telegram Bot
+
+1. Open Telegram and search for [@BotFather](https://t.me/BotFather)
+2. Send `/newbot` and follow the prompts
+3. Save the bot token provided
+
+### 2. Install TeleMux
+
+```bash
+# Install via pip
+pip install telemux
+
+# Run the interactive installer
+telemux install
+```
+
+The installer will:
+- Check prerequisites (tmux, python3, curl)
+- Validate your bot token
+- Auto-detect available chats (with retry logic)
+- Create configuration files
+- Install shell functions
+- Test the connection
+
+### 3. Start the Listener
+
+```bash
+# Start the daemon
+telemux start
+
+# Check status
+telemux status
+
+# View logs
+telemux logs
+```
+
+### 4. Use Shell Functions
+
+```bash
+# Send a simple notification
+tg_alert "Build complete!"
+
+# Send a message and receive replies
+tg_agent "deploy-agent" "Ready to deploy to production?"
+# Reply via Telegram: "session-name: yes"
+# The reply appears directly in your terminal
+
+# Get notified when a command completes
+npm run build && tg_done
+```
+
+## Commands
+
+### Control Commands
+
+```bash
+telemux start       # Start the listener daemon
+telemux stop        # Stop the listener daemon
+telemux restart     # Restart the listener daemon
+telemux status      # Check daemon status
+telemux logs        # View listener logs (tail -f)
+telemux attach      # Attach to the listener tmux session
+telemux cleanup     # Rotate and clean up log files
+telemux doctor      # Run health check and diagnose issues
+telemux install     # Run interactive installer
+```
+
+### Shortcuts
+
+For convenience, all commands have `tg-` shortcuts:
+
+```bash
+tg-start    # Same as: telemux start
+tg-stop     # Same as: telemux stop
+tg-status   # Same as: telemux status
+tg-logs     # Same as: telemux logs
+```
+
+## Shell Functions
+
+After installation, these functions are available in your shell:
+
+### `tg_alert`
+
+Send one-way notifications to Telegram:
+
+```bash
+tg_alert "Message text"
+```
+
+**Examples:**
+
+```bash
+# Simple notification
+tg_alert "Server is ready"
+
+# Notify when command completes
+npm install && tg_alert "Dependencies installed"
+
+# Multiline messages
+tg_alert "Deploy complete
+- 50 files updated
+- 0 errors"
+```
+
+### `tg_agent`
+
+Send messages and receive replies via Telegram:
+
+```bash
+tg_agent "agent-name" "Message text"
+```
+
+**Examples:**
+
+```bash
+# Ask a question
+tg_agent "deploy-agent" "Ready to deploy to production?"
+
+# Wait for user response via Telegram
+# User replies: "session-name: yes, proceed"
+# Reply appears in your terminal
+
+# Use in scripts
+response=$(tg_agent "approval-agent" "Approve release v2.0?")
+if [[ "$response" == *"yes"* ]]; then
+    ./deploy.sh
+fi
+```
+
+### `tg_done`
+
+Automatically notify when the previous command completes:
+
+```bash
+npm run build && tg_done
+```
+
+This sends a notification with:
+- Command that ran
+- Exit code (success/failure)
+- Timestamp
+
+## Bidirectional Communication
+
+TeleMux uses **session-based routing** for bidirectional communication:
+
+### Sending Messages from Terminal
+
+```bash
+# In tmux session named "deploy"
+tg_agent "deploy-check" "Should I proceed with deployment?"
+```
+
+This sends a message to Telegram with instructions on how to reply.
+
+### Replying from Telegram
+
+Reply with the format: `session-name: your message`
+
+```
+deploy: yes, proceed with deployment
+```
+
+The reply is automatically routed to the correct tmux session and appears in your terminal.
+
+### Security
+
+- Messages are routed **only** to existing tmux sessions
+- User input is sanitized to prevent command injection
+- Session names are validated before routing
+- No session names are revealed in error messages
+
+## Configuration
+
+Configuration is stored in `~/.telemux/`:
+
+```
+~/.telemux/
+├── telegram_config          # Bot token and chat ID (chmod 600)
+├── telegram_listener.log    # Listener daemon logs
+├── telegram_errors.log      # Error logs
+├── message_queue/           # Message routing data
+│   ├── outgoing.log        # Sent messages
+│   ├── incoming.log        # Received messages
+│   └── archive/            # Rotated logs
+└── shell_functions.sh       # Shell integration functions
+```
+
+### Environment Variables
+
+You can override configuration with environment variables:
+
+```bash
+export TELEMUX_TG_BOT_TOKEN="your-bot-token"
+export TELEMUX_TG_CHAT_ID="your-chat-id"
+export TELEMUX_LOG_LEVEL="DEBUG"  # DEBUG, INFO, WARNING, ERROR
+```
+
+## Log Management
+
+Logs are automatically rotated when they exceed 10MB:
+
+```bash
+# Manual log rotation
+telemux cleanup
+
+# Install automatic monthly cleanup
+telemux cleanup --install-cron
+```
+
+Archives are stored in `~/.telemux/message_queue/archive/` and compressed with gzip.
+
+## Troubleshooting
+
+### Run Health Check
+
+```bash
+telemux doctor
+```
+
+This checks:
+- Prerequisites (tmux, python3)
+- Configuration files
+- Telegram bot connection
+- Listener daemon status
+- Log files
+
+### Common Issues
+
+**Listener won't start:**
+```bash
+# Check if it's already running
+telemux status
+
+# View logs for errors
+telemux logs
+
+# Restart the listener
+telemux restart
+```
+
+**Messages not being received:**
+```bash
+# Check listener status
+telemux status
+
+# Verify configuration
+cat ~/.telemux/telegram_config
+
+# Test bot connection
+telemux doctor
+```
+
+**Shell functions not available:**
+```bash
+# Reload your shell configuration
+source ~/.zshrc  # or ~/.bashrc
+
+# Verify functions are sourced
+type tg_alert
+```
+
+## Examples
+
+### Long-Running Build Notification
+
+```bash
+#!/bin/bash
+# Build script with notification
+
+echo "Starting build..."
+tg_alert "Build started for project-x"
+
+npm run build
+if [ $? -eq 0 ]; then
+    tg_alert "Build succeeded!"
+else
+    tg_alert "Build failed! Check logs."
+fi
+```
+
+### Interactive Deployment Agent
+
+```bash
+#!/bin/bash
+# Deployment with approval
+
+tg_agent "deploy-agent" "Ready to deploy v2.0 to production?"
+
+# User responds via Telegram: "session-name: yes"
+# Response appears in terminal
+
+read -p "Proceed with deployment? " response
+if [[ "$response" == *"yes"* ]]; then
+    ./deploy.sh
+    tg_alert "Deployment complete!"
+fi
+```
+
+### Multi-Step Workflow
+
+```bash
+#!/bin/bash
+# Complex workflow with multiple checkpoints
+
+tg_alert "Starting migration workflow..."
+
+# Step 1: Backup
+tg_agent "migration-agent" "Backup database before migration?"
+# Wait for approval...
+
+# Step 2: Migration
+./run-migration.sh && tg_done
+
+# Step 3: Verification
+tg_agent "migration-agent" "Verify migration results?"
+# Wait for verification...
+
+tg_alert "Migration workflow complete!"
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run with coverage
+pytest --cov=telemux --cov-report=term-missing
+```
+
+### Project Structure
+
+```
+telemux/
+├── telemux/
+│   ├── __init__.py       # Package initialization
+│   ├── cli.py            # Main CLI entry point
+│   ├── control.py        # Daemon control (start, stop, status)
+│   ├── listener.py       # Telegram listener daemon
+│   ├── installer.py      # Interactive installer
+│   ├── cleanup.py        # Log rotation and cleanup
+│   ├── config.py         # Configuration management
+│   └── shell_functions.sh # Shell integration
+├── examples/             # Example scripts
+├── tests/               # Test suite
+├── pyproject.toml       # Package metadata and dependencies
+├── MANIFEST.in          # Package file manifest
+└── README.md            # This file
+```
+
+## Requirements
+
+- Python 3.7+
+- tmux
+- curl
+- requests library (automatically installed)
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history.
+
+## Support
+
+- GitHub Issues: https://github.com/malmazan/telemux/issues
+- Documentation: https://github.com/malmazan/telemux
+
+## Credits
+
+Created by Marco Almazan
+
+## Related Projects
+
+- [tmux](https://github.com/tmux/tmux) - Terminal multiplexer
+- [python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot) - Telegram Bot API wrapper