onecmd 0.2.0__tar.gz

onecmd-0.2.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 antirez (original tgterm)
+Copyright (c) 2026 Erik
+
+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.

onecmd-0.2.0/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: onecmd
+Version: 0.2.0
+Summary: AI-powered terminal manager — control and automate your machines from Telegram
+Author: Erik
+License: MIT
+Project-URL: Homepage, https://github.com/warlockee/1cmd-ai
+Project-URL: Repository, https://github.com/warlockee/1cmd-ai
+Project-URL: Issues, https://github.com/warlockee/1cmd-ai/issues
+Keywords: telegram,terminal,ai,automation,remote
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-telegram-bot>=21.0
+Requires-Dist: google-genai>=1.0.0
+Requires-Dist: anthropic>=0.39.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: qrcode>=7.0
+Provides-Extra: macos
+Requires-Dist: pyobjc-framework-Quartz; extra == "macos"
+Requires-Dist: pyobjc-framework-ApplicationServices; extra == "macos"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# OneCmd
+
+An AI-powered terminal manager — control and automate your machines from Telegram.
+
+Works on **macOS** and **Linux**.
+
+> **One bot per machine.** Each machine needs its own Telegram bot token. Create a separate bot for each machine you want to control (e.g. `@my_macbook_bot`, `@my_server_bot`). Only one onecmd instance can use a given bot token at a time.
+
+## Quick Start
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/warlockee/1cmd-ai/main/setup.sh | bash
+```
+
+The setup script handles everything: clones the repo, installs Python dependencies, configures your Telegram bot and AI provider, and starts onecmd.
+
+Or install manually:
+
+```bash
+git clone https://github.com/warlockee/1cmd-ai.git
+cd 1cmd-ai
+python3 -m venv .venv
+.venv/bin/pip install ".[macos]"   # macOS (or just "." for Linux)
+.venv/bin/onecmd --apikey YOUR_BOT_TOKEN
+```
+
+## AI Manager
+
+The AI manager is what makes OneCmd powerful. It's an LLM-powered agent that monitors, controls, and automates your terminals — so you can manage servers, run deployments, and debug issues all from a Telegram chat.
+
+Send `.mgr` to enter manager mode. Your messages go to the AI agent, which can see and interact with all your terminals. Dot commands (`.list`, `.1`, etc.) still work normally. Send `.exit` to leave manager mode.
+
+### What it can do
+
+- List, read, and send commands to any terminal
+- Name terminals for easy identification (proactively suggests names based on content)
+- Execute commands asynchronously and notify you when they finish
+- Queue commands to the same terminal so they don't overlap
+- Auto-detect pending commands at prompts and submit them
+- Follow up on completed commands (results feed back to the LLM)
+- Run repeating background tasks ("watch this terminal until X happens")
+- Detect and recover stuck terminals (Smart Diff — probe, compare before/after)
+- Summarize long conversations to preserve context within token limits
+- Auto-fallback between Gemini and Claude on rate limits
+- Remember things across restarts (persistent memory)
+
+### Providers
+
+The manager supports **Gemini** (Google) and **Claude** (Anthropic). The provider is selected automatically based on which API key is set. If both are set, Gemini is preferred. Override the model with `ONECMD_MGR_MODEL`.
+
+```bash
+# Using Gemini (recommended — fast and free tier available)
+GOOGLE_API_KEY=... onecmd --apikey YOUR_BOT_TOKEN
+
+# Using Claude
+ANTHROPIC_API_KEY=sk-... onecmd --apikey YOUR_BOT_TOKEN
+```
+
+### Standard Operating Procedure
+
+On first run, the manager copies the default SOP to `.onecmd/agent_sop.md`. This file guides the AI on decision-making and stuck terminal recovery.
+
+To add your own rules, create `.onecmd/custom_rules.md`:
+
+```markdown
+- Always run tests before deploying
+- Never restart the database without asking me first
+- Prefer yarn over npm
+```
+
+Custom rules are appended to the default SOP automatically — no need to edit the base file.
+
+### Manager commands
+
+| Command | Action |
+|---------|--------|
+| `.mgr` | Enter AI manager mode |
+| `.exit` | Leave manager mode |
+| `.health` | Manager health report (uptime, memory, stats) |
+
+## Manual Mode
+
+Manual mode is always available as a stable, reliable fallback. It works without any AI provider — just you and your terminals over Telegram. No API keys, no token limits, no network dependencies beyond Telegram itself. When the AI is down or you need direct control, manual mode is always there.
+
+In manual mode, any text you send is typed directly into the connected terminal as keystrokes.
+
+| Command | Action |
+|---------|--------|
+| `.list` | List available terminal sessions |
+| `.1` `.2` ... | Connect to a session by number |
+| `.rename <N> <name>` | Name a terminal for easy identification |
+| `.help` | Show all commands |
+| Any other text | Sent as keystrokes to the connected terminal |
+
+### Keystroke Modifiers
+
+Prefix your message with an emoji to add a modifier key:
+
+| Emoji | Modifier | Example |
+|-------|----------|---------|
+| `❤️` | Ctrl | `❤️c` = Ctrl+C |
+| `💙` | Alt | `💙x` = Alt+X |
+| `💚` | Cmd | macOS only |
+| `💛` | ESC | `💛` = send Escape |
+| `🧡` | Enter | `🧡` = send Enter |
+| `💜` | Suppress auto-newline | `ls -la💜` = no Enter appended |
+
+### Escape Sequences
+
+`\n` for Enter, `\t` for Tab, `\\` for literal backslash.
+
+## How It Works
+
+On **macOS**, onecmd reads terminal window text via the Accessibility API (`AXUIElement`), injects keystrokes via `CGEvent`, and focuses windows using `AXUIElement`. It works with any terminal app — no Screen Recording permission needed.
+
+On **Linux**, onecmd uses tmux: `tmux list-panes` to discover sessions, `tmux capture-pane` to read content, and `tmux send-keys` to inject keystrokes. All sessions you want to control must run inside tmux.
+
+In both cases, terminal output is sent as monospace text to Telegram with a refresh button to update on demand.
+
+### Linux: tmux requirement
+
+On Linux, onecmd controls tmux sessions. Make sure your work is running inside tmux:
+
+```bash
+# Start a named session
+tmux new -s dev
+
+# Or start detached sessions
+tmux new -s server1 -d
+tmux new -s server2 -d
+```
+
+Then run onecmd separately (outside tmux or in its own tmux window) and use `.list` to see your sessions.
+
+## Configuration
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--apikey <token>` | Telegram bot API token |
+| `--enable-otp` | Enable TOTP authentication (off by default) |
+| `--use-weak-security` | Disable TOTP even if previously configured |
+| `--dbfile <path>` | Custom database path (default: `./mybot.sqlite`) |
+| `--dangerously-attach-to-any-window` | Show all windows, not just terminals (macOS only) |
+| `--verbose` | Enable debug logging |
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GOOGLE_API_KEY` | (none) | Google API key for the AI manager (Gemini) |
+| `ANTHROPIC_API_KEY` | (none) | Anthropic API key for the AI manager (Claude) |
+| `ONECMD_MGR_MODEL` | (auto) | LLM model override |
+| `ONECMD_VISIBLE_LINES` | `40` | Number of terminal lines to include in output |
+| `ONECMD_SPLIT_MESSAGES` | off | Set to `1` to split long output across multiple messages |
+
+Terminal output is sent as a single message by default. Each new command or refresh **deletes the previous output messages** and sends fresh ones, creating a clean "live terminal" view rather than spamming the chat.
+
+If your terminal produces very long output (e.g. build logs) and you want to see all of it, enable splitting:
+
+```bash
+ONECMD_SPLIT_MESSAGES=1 onecmd --apikey YOUR_BOT_TOKEN
+```
+
+### Prerequisites
+
+- **Python 3.11+**
+- **macOS:** Accessibility permission (prompted on first use)
+- **Linux:** `tmux`
+
+### Manual Run
+
+```bash
+# Create venv and install
+python3 -m venv .venv
+.venv/bin/pip install ".[macos]"   # macOS
+.venv/bin/pip install .            # Linux
+
+# Run with AI manager
+GOOGLE_API_KEY=... .venv/bin/onecmd --apikey YOUR_BOT_TOKEN
+
+# Run without AI manager (manual mode only)
+.venv/bin/onecmd --apikey YOUR_BOT_TOKEN
+```
+
+## Security
+
+- **Owner lock**: The first Telegram user to message the bot becomes the owner. All other users are ignored.
+- **TOTP**: OTP is **off by default** for a frictionless first-time experience. Use `--enable-otp` to set up Google Authenticator — a QR code is shown on first launch. Use `--use-weak-security` to disable OTP even if previously configured.
+- **One bot = one machine**: Don't share a bot token across machines. Each machine should have its own bot.
+- **Reset**: Delete `mybot.sqlite` to reset ownership and TOTP.
+
+## Permissions
+
+**macOS:** Requires Accessibility permission. macOS will prompt on first use, or grant it in System Settings > Privacy & Security > Accessibility.
+
+**Linux:** No special permissions needed. Just ensure the user running onecmd can access the tmux socket.
+
+## Supported Terminals
+
+**macOS:** Terminal.app, iTerm2, Ghostty, kitty, Alacritty, Hyper, Warp, WezTerm, Tabby.
+
+**Linux:** Any terminal running inside tmux.
+
+## Architecture
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for detailed technical documentation.
+
+## License
+
+MIT -- see [LICENSE](LICENSE).

onecmd-0.2.0/README.md

@@ -0,0 +1,212 @@
+# OneCmd
+
+An AI-powered terminal manager — control and automate your machines from Telegram.
+
+Works on **macOS** and **Linux**.
+
+> **One bot per machine.** Each machine needs its own Telegram bot token. Create a separate bot for each machine you want to control (e.g. `@my_macbook_bot`, `@my_server_bot`). Only one onecmd instance can use a given bot token at a time.
+
+## Quick Start
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/warlockee/1cmd-ai/main/setup.sh | bash
+```
+
+The setup script handles everything: clones the repo, installs Python dependencies, configures your Telegram bot and AI provider, and starts onecmd.
+
+Or install manually:
+
+```bash
+git clone https://github.com/warlockee/1cmd-ai.git
+cd 1cmd-ai
+python3 -m venv .venv
+.venv/bin/pip install ".[macos]"   # macOS (or just "." for Linux)
+.venv/bin/onecmd --apikey YOUR_BOT_TOKEN
+```
+
+## AI Manager
+
+The AI manager is what makes OneCmd powerful. It's an LLM-powered agent that monitors, controls, and automates your terminals — so you can manage servers, run deployments, and debug issues all from a Telegram chat.
+
+Send `.mgr` to enter manager mode. Your messages go to the AI agent, which can see and interact with all your terminals. Dot commands (`.list`, `.1`, etc.) still work normally. Send `.exit` to leave manager mode.
+
+### What it can do
+
+- List, read, and send commands to any terminal
+- Name terminals for easy identification (proactively suggests names based on content)
+- Execute commands asynchronously and notify you when they finish
+- Queue commands to the same terminal so they don't overlap
+- Auto-detect pending commands at prompts and submit them
+- Follow up on completed commands (results feed back to the LLM)
+- Run repeating background tasks ("watch this terminal until X happens")
+- Detect and recover stuck terminals (Smart Diff — probe, compare before/after)
+- Summarize long conversations to preserve context within token limits
+- Auto-fallback between Gemini and Claude on rate limits
+- Remember things across restarts (persistent memory)
+
+### Providers
+
+The manager supports **Gemini** (Google) and **Claude** (Anthropic). The provider is selected automatically based on which API key is set. If both are set, Gemini is preferred. Override the model with `ONECMD_MGR_MODEL`.
+
+```bash
+# Using Gemini (recommended — fast and free tier available)
+GOOGLE_API_KEY=... onecmd --apikey YOUR_BOT_TOKEN
+
+# Using Claude
+ANTHROPIC_API_KEY=sk-... onecmd --apikey YOUR_BOT_TOKEN
+```
+
+### Standard Operating Procedure
+
+On first run, the manager copies the default SOP to `.onecmd/agent_sop.md`. This file guides the AI on decision-making and stuck terminal recovery.
+
+To add your own rules, create `.onecmd/custom_rules.md`:
+
+```markdown
+- Always run tests before deploying
+- Never restart the database without asking me first
+- Prefer yarn over npm
+```
+
+Custom rules are appended to the default SOP automatically — no need to edit the base file.
+
+### Manager commands
+
+| Command | Action |
+|---------|--------|
+| `.mgr` | Enter AI manager mode |
+| `.exit` | Leave manager mode |
+| `.health` | Manager health report (uptime, memory, stats) |
+
+## Manual Mode
+
+Manual mode is always available as a stable, reliable fallback. It works without any AI provider — just you and your terminals over Telegram. No API keys, no token limits, no network dependencies beyond Telegram itself. When the AI is down or you need direct control, manual mode is always there.
+
+In manual mode, any text you send is typed directly into the connected terminal as keystrokes.
+
+| Command | Action |
+|---------|--------|
+| `.list` | List available terminal sessions |
+| `.1` `.2` ... | Connect to a session by number |
+| `.rename <N> <name>` | Name a terminal for easy identification |
+| `.help` | Show all commands |
+| Any other text | Sent as keystrokes to the connected terminal |
+
+### Keystroke Modifiers
+
+Prefix your message with an emoji to add a modifier key:
+
+| Emoji | Modifier | Example |
+|-------|----------|---------|
+| `❤️` | Ctrl | `❤️c` = Ctrl+C |
+| `💙` | Alt | `💙x` = Alt+X |
+| `💚` | Cmd | macOS only |
+| `💛` | ESC | `💛` = send Escape |
+| `🧡` | Enter | `🧡` = send Enter |
+| `💜` | Suppress auto-newline | `ls -la💜` = no Enter appended |
+
+### Escape Sequences
+
+`\n` for Enter, `\t` for Tab, `\\` for literal backslash.
+
+## How It Works
+
+On **macOS**, onecmd reads terminal window text via the Accessibility API (`AXUIElement`), injects keystrokes via `CGEvent`, and focuses windows using `AXUIElement`. It works with any terminal app — no Screen Recording permission needed.
+
+On **Linux**, onecmd uses tmux: `tmux list-panes` to discover sessions, `tmux capture-pane` to read content, and `tmux send-keys` to inject keystrokes. All sessions you want to control must run inside tmux.
+
+In both cases, terminal output is sent as monospace text to Telegram with a refresh button to update on demand.
+
+### Linux: tmux requirement
+
+On Linux, onecmd controls tmux sessions. Make sure your work is running inside tmux:
+
+```bash
+# Start a named session
+tmux new -s dev
+
+# Or start detached sessions
+tmux new -s server1 -d
+tmux new -s server2 -d
+```
+
+Then run onecmd separately (outside tmux or in its own tmux window) and use `.list` to see your sessions.
+
+## Configuration
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--apikey <token>` | Telegram bot API token |
+| `--enable-otp` | Enable TOTP authentication (off by default) |
+| `--use-weak-security` | Disable TOTP even if previously configured |
+| `--dbfile <path>` | Custom database path (default: `./mybot.sqlite`) |
+| `--dangerously-attach-to-any-window` | Show all windows, not just terminals (macOS only) |
+| `--verbose` | Enable debug logging |
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GOOGLE_API_KEY` | (none) | Google API key for the AI manager (Gemini) |
+| `ANTHROPIC_API_KEY` | (none) | Anthropic API key for the AI manager (Claude) |
+| `ONECMD_MGR_MODEL` | (auto) | LLM model override |
+| `ONECMD_VISIBLE_LINES` | `40` | Number of terminal lines to include in output |
+| `ONECMD_SPLIT_MESSAGES` | off | Set to `1` to split long output across multiple messages |
+
+Terminal output is sent as a single message by default. Each new command or refresh **deletes the previous output messages** and sends fresh ones, creating a clean "live terminal" view rather than spamming the chat.
+
+If your terminal produces very long output (e.g. build logs) and you want to see all of it, enable splitting:
+
+```bash
+ONECMD_SPLIT_MESSAGES=1 onecmd --apikey YOUR_BOT_TOKEN
+```
+
+### Prerequisites
+
+- **Python 3.11+**
+- **macOS:** Accessibility permission (prompted on first use)
+- **Linux:** `tmux`
+
+### Manual Run
+
+```bash
+# Create venv and install
+python3 -m venv .venv
+.venv/bin/pip install ".[macos]"   # macOS
+.venv/bin/pip install .            # Linux
+
+# Run with AI manager
+GOOGLE_API_KEY=... .venv/bin/onecmd --apikey YOUR_BOT_TOKEN
+
+# Run without AI manager (manual mode only)
+.venv/bin/onecmd --apikey YOUR_BOT_TOKEN
+```
+
+## Security
+
+- **Owner lock**: The first Telegram user to message the bot becomes the owner. All other users are ignored.
+- **TOTP**: OTP is **off by default** for a frictionless first-time experience. Use `--enable-otp` to set up Google Authenticator — a QR code is shown on first launch. Use `--use-weak-security` to disable OTP even if previously configured.
+- **One bot = one machine**: Don't share a bot token across machines. Each machine should have its own bot.
+- **Reset**: Delete `mybot.sqlite` to reset ownership and TOTP.
+
+## Permissions
+
+**macOS:** Requires Accessibility permission. macOS will prompt on first use, or grant it in System Settings > Privacy & Security > Accessibility.
+
+**Linux:** No special permissions needed. Just ensure the user running onecmd can access the tmux socket.
+
+## Supported Terminals
+
+**macOS:** Terminal.app, iTerm2, Ghostty, kitty, Alacritty, Hyper, Warp, WezTerm, Tabby.
+
+**Linux:** Any terminal running inside tmux.
+
+## Architecture
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for detailed technical documentation.
+
+## License
+
+MIT -- see [LICENSE](LICENSE).

onecmd-0.2.0/onecmd/auth/owner.py

@@ -0,0 +1,45 @@
+"""Owner registration and verification.
+
+Calling spec:
+  Inputs:  Store instance, user_id (int)
+  Outputs: tuple[bool, bool] — (is_owner, just_registered)
+  Side effects: writes "owner_id" to store on first-ever call
+
+Logic:
+  1. Read "owner_id" from store (O(1) SQLite lookup).
+  2. If no owner registered, register this user as owner.
+     Return (True, True).
+  3. If owner exists and matches user_id, return (True, False).
+  4. If owner exists and does NOT match, return (False, False).
+
+Guarding:
+  - First user to message becomes owner (stored via store.set)
+  - No mechanism to change owner at runtime
+  - Owner check is O(1) lookup, not bypassable
+"""
+
+from __future__ import annotations
+
+from onecmd.store import Store
+
+OWNER_KEY = "owner_id"
+
+
+def check_owner(store: Store, user_id: int) -> tuple[bool, bool]:
+    """Check whether *user_id* is the bot owner.
+
+    Returns ``(is_owner, just_registered)``.
+
+    On the very first call (no owner in the store), the caller is
+    registered as owner and ``(True, True)`` is returned.  All
+    subsequent calls compare against the stored owner ID.
+    """
+    stored = store.get(OWNER_KEY)
+
+    # First user becomes owner.
+    if stored is None:
+        store.set(OWNER_KEY, str(user_id))
+        return True, True
+
+    is_owner = stored == str(user_id)
+    return is_owner, False