botable-dev 0.3.1__py3-none-any.whl

botable_dev-0.3.1.dist-info/METADATA

@@ -0,0 +1,186 @@
+Metadata-Version: 2.5
+Name: botable-dev
+Version: 0.3.1
+Summary: Botable CLI: build, deploy and run Telegram bots from your terminal, Claude Code or Codex
+Project-URL: Homepage, https://botable.dev
+Author-email: Botable Team <hello@botable.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,aiogram,bot,chatbot,cli,generator,telegram
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: openai>=1.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: rich>=13.0
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: typer>=0.15
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.11; extra == 'dev'
+Requires-Dist: twine>=6.0; extra == 'dev'
+Requires-Dist: watchfiles>=1.0; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# ⚡ Botable CLI
+
+> **Generate Telegram bots with AI — from idea to running bot in 3 minutes.**
+
+[![PyPI](https://img.shields.io/pypi/v/botable-dev?color=blue)](https://pypi.org/project/botable-dev/)
+[![Python](https://img.shields.io/pypi/pyversions/botable-dev)](https://pypi.org/project/botable-dev/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+## Quick Start
+
+```bash
+pip install "botable-dev[mcp]"
+botable login
+botable mcp install
+
+# Create a project
+botable init my-bot
+cd my-bot
+
+# Add your keys to .env
+echo "BOT_TOKEN=your-telegram-token" >> .env
+echo "OPENAI_API_KEY=sk-..." >> .env
+
+# Generate a bot from a description
+botable generate "a FAQ bot for my restaurant with menu and hours"
+
+# Run locally
+botable dev
+```
+
+**That's it.** Your bot is running in under 3 minutes.
+
+## Commands
+
+### Local Development
+
+| Command | Description |
+|---------|-------------|
+| `botable init [name]` | Scaffold a new bot project |
+| `botable generate "description"` | Generate bot from natural language |
+| `botable dev` | Run bot locally with live output |
+| `botable dev --watch` | Run with hot reload on file changes |
+| `botable version` | Show CLI version and effective API URL |
+
+### Cloud Deployment
+
+| Command | Description |
+|---------|-------------|
+| `botable login [--no-browser]` | Sign in through the browser |
+| `botable login --api-key KEY [--api-url URL]` | Save an existing API key and API URL |
+| `botable mcp install [--target claude\|codex\|all] [--scope user\|project]` | Configure agent MCP clients |
+| `botable logout` | Remove stored authentication |
+| `botable deploy` | Deploy to Botable cloud |
+| `botable logs [project_id]` | Show the current bot status snapshot |
+| `botable bots list` | List all deployed bots |
+| `botable bots stop {id}` | Stop a running bot |
+
+## Deploy to Cloud
+
+```bash
+botable login
+
+# Deploy your bot
+botable deploy
+
+# Check status
+botable bots list
+botable logs
+```
+
+## Configuration
+
+Botable uses a 3-layer config system:
+
+| File | Scope | Purpose |
+|------|-------|---------| 
+| `botable.toml` | Project | Bot name, template, branding (committed to git) |
+| `.env` | Project | Secrets: BOT_TOKEN, API keys (NOT committed) |
+| `~/.config/botable/config.toml` | User | Global defaults, auth token |
+
+`botable login --api-url URL` saves the API URL. `BOTABLE_API_URL` overrides it for the current process; otherwise the default is `https://api-staging.botable.dev` (staging, until the CLI routes reach production). Run `botable version` to see the effective URL.
+
+## Use Botable from Claude Code / Codex
+
+In Botable's **Code** tab, export your bot project. The export contains `botable.toml` with the project ID. Edit the files locally, then run `botable deploy` from that directory to deploy the same project. The CLI deployment routes currently work on staging, which is the default API URL:
+
+```bash
+botable login
+botable mcp install
+botable version
+cd path/to/exported-bot
+botable deploy
+botable bots list
+botable logs PROJECT_ID
+```
+
+**`botable deploy` uploads the project's `.env` file**, including any secrets in it. Check its contents before deployment. `botable logs` currently returns a status snapshot; runtime log lines and live streaming are not available through the CLI API yet.
+
+`botable mcp install` registers the installed `botable-mcp` executable with Claude Code and Codex. Use `--target` to select one client. Claude uses its `claude mcp add` command when installed; without Claude, `--scope project` writes project `.mcp.json` (the default user scope requires Claude). Codex configuration goes in `~/.codex/config.toml` with a backup of an existing file. Check with `claude mcp list` or `codex mcp list`.
+
+The MCP server exposes project creation, generation, templates, local development, deployment, bot listing, status, and the available status snapshot through its logs tool. Its former SSH staging status tool was removed because it requires operator access and is unrelated to customer bots. The MCP server uses the API URL and key saved by `botable login` (or the `BOTABLE_API_URL` environment override).
+
+### Branding
+
+Every generated bot includes a `# Built with Botable` comment. Customize or disable it:
+
+```toml
+# In botable.toml (per-project)
+[branding]
+enabled = true
+text = "Built with Botable (botable.dev)"
+style = "comment"  # "comment" | "docstring" | "none"
+```
+
+To disable globally:
+
+```toml
+# In ~/.config/botable/config.toml
+[branding]
+enabled = false
+```
+
+## How It Works
+
+1. **`botable init`** — creates project structure with `botable.toml` + `.env`
+2. **`botable generate`** — calls OpenAI to generate aiogram bot code, validates syntax, writes `main.py` + `requirements.txt`
+3. **`botable dev`** — creates a venv, installs deps, runs your bot with live output
+4. **`botable deploy`** — packages project, uploads to Botable cloud, deploys automatically
+
+Generated bots use [aiogram](https://docs.aiogram.dev/) (MIT license) — async-native, production-ready.
+
+## Development
+
+```bash
+git clone https://github.com/Botable-dev/cli.git
+cd cli
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.
+
+---
+
+⚡ Built with [Botable](https://botable.dev)

botable_dev-0.3.1.dist-info/RECORD

@@ -0,0 +1,19 @@
+botable_mcp/__init__.py,sha256=TKpuc88IMV3Q00TGXxy1YC4I8osp25e1yMO7zG_jNy8,110
+botable_mcp/server.py,sha256=hW8ScxWiiFkZTlQZEVLDvzCOKk51dRflwiym2bPHvMU,7076
+botable/__init__.py,sha256=ksjdI3KL6Mta5q4HTkFYnM7ZU0-cd_OzeSQLZbp7LWI,77
+botable/__main__.py,sha256=CzzADKdeKBZI0C_blAPwBozHX2toCZ-6CXqn5NJCR48,80
+botable/api_client.py,sha256=zPmoqrqESLtmcpSpTutUQu1cQ266tANS0p3yISjMpLE,7759
+botable/cli.py,sha256=JNFKf6NUfwkwkVTaIEFvdKZ7ck0O40qWLftFrHFtod0,28399
+botable/config.py,sha256=iBeDGIrkXtEOT3o_swSvFcBTAzRVUdNOKl5MrYGH7ew,6125
+botable/errors.py,sha256=4O6fktllLnLh--_j_mhZ4abvGZHGeV96WK2vb1kWE8Q,1582
+botable/generate.py,sha256=Hguvv-3Ymetsh70XNvde-LJb3n8GTrORjWj4kOS1toE,10383
+botable/mcp_install.py,sha256=GNudNSi_55CmTnFVONisKzm2NiVGfNeCfpEw_AZCgyw,3173
+botable/prompts.py,sha256=kXufqo5dOK0rmuWm-rlAPIvA9Gz3WScO3H3JKJM6wgw,4334
+botable/runner.py,sha256=Jey6ybaOo0OxTJA6el_OY5iEVIkY5wyL3TP4Iue5om4,10915
+botable/scaffold.py,sha256=-r3eDzh7uDlBEbOmWlOoemMnghjEmFBHJWhF66oJdlQ,2161
+botable/ui.py,sha256=zRE0dFuDgI7ycBqSrMMfkjS2FsXvLwK9awbjP9W5WKY,1161
+botable_dev-0.3.1.dist-info/METADATA,sha256=e4MKKstKSYruGmCjsEt30oc1ibzdVBa1IpPwFnzLA6c,6722
+botable_dev-0.3.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+botable_dev-0.3.1.dist-info/entry_points.txt,sha256=Pa6hdEApZYHGfTJEOc8switJQpwm5j3fAWbKyGXGGdM,82
+botable_dev-0.3.1.dist-info/licenses/LICENSE,sha256=EXuJ5sHNeoVo7syFduoLoze4FE3EfQx1O8uXCy3lFE4,1067
+botable_dev-0.3.1.dist-info/RECORD,,

botable_dev-0.3.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

botable_dev-0.3.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+botable = botable.cli:app
+botable-mcp = botable_mcp.server:main

botable_dev-0.3.1.dist-info/licenses/LICENSE

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

botable_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Botable MCP Server — exposes Botable CLI tools via the Model Context Protocol."""
+
+__version__ = "0.1.0"

botable_mcp/server.py

@@ -0,0 +1,227 @@
+#!/usr/bin/env python3
+"""
+Botable MCP Server
+
+Exposes Botable CLI tools over the Model Context Protocol (stdio transport)
+for integration with Claude Code and other MCP-aware clients.
+
+Tools:
+  - botable_init       Create a new bot project
+  - botable_generate   Generate bot code from a description
+  - botable_templates  List available templates
+  - botable_dev        Run a bot locally (background process)
+  - botable_deploy     Deploy a local bot project
+  - botable_bots_list  List deployed bots
+  - botable_bot_status Get a bot's status snapshot
+  - botable_bot_logs   Get the same snapshot (runtime logs unavailable)
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+try:
+    from mcp.server.fastmcp import FastMCP
+except ModuleNotFoundError as exc:
+    if exc.name != "mcp":
+        raise
+    FastMCP = None
+
+mcp = FastMCP("botable", instructions="Botable CLI tools for Telegram bots") if FastMCP else None
+tool = mcp.tool if mcp else lambda: lambda fn: fn
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+DEFAULT_TIMEOUT = 120
+
+
+def _botable_command() -> list[str]:
+    """Find the CLI, preferring an explicit executable and the user's PATH."""
+    override = os.environ.get("BOTABLE_CMD")
+    if override:
+        return [override]
+    on_path = shutil.which("botable")
+    if on_path:
+        return [on_path]
+    sibling = Path(sys.executable).with_name("botable")
+    if sibling.is_file() and os.access(sibling, os.X_OK):
+        return [str(sibling)]
+    if importlib.util.find_spec("botable") and importlib.util.find_spec("botable.__main__"):
+        return [sys.executable, "-m", "botable"]
+    raise FileNotFoundError("Botable CLI not found. Install botable in this Python environment or set BOTABLE_CMD to its executable path.")
+
+
+async def run_botable(args: list[str], cwd: str | None = None) -> str:
+    """Run a botable CLI command and return its output."""
+    try:
+        result = subprocess.run(
+            _botable_command() + args,
+            capture_output=True,
+            text=True,
+            cwd=cwd,
+            timeout=DEFAULT_TIMEOUT,
+        )
+    except FileNotFoundError as exc:
+        return f"Error: {exc}"
+    except subprocess.TimeoutExpired:
+        return f"Error: command timed out after {DEFAULT_TIMEOUT}s"
+
+    if result.returncode != 0:
+        stderr = result.stderr.strip()
+        stdout = result.stdout.strip()
+        detail = stderr or stdout or "(no output)"
+        return f"Error (exit {result.returncode}): {detail}"
+
+    return result.stdout
+
+
+def _list_created_files(directory: str) -> list[str]:
+    """Return a list of files under *directory*, relative to it."""
+    base = Path(directory)
+    if not base.is_dir():
+        return []
+    return sorted(
+        str(p.relative_to(base))
+        for p in base.rglob("*")
+        if p.is_file()
+    )
+
+
+# ---------------------------------------------------------------------------
+# Tools
+# ---------------------------------------------------------------------------
+
+
+@tool()
+async def botable_init(name: str, directory: str) -> str:
+    """Create a new Botable bot project.
+
+    Args:
+        name: Project / bot name (e.g. "my-bot").
+        directory: Absolute path to the parent directory where the project
+                   folder will be created.
+    """
+    directory = os.path.expanduser(directory)
+    output = await run_botable(["init", name], cwd=directory)
+
+    if output.startswith("Error"):
+        return output
+
+    project_dir = os.path.join(directory, name)
+    files = _list_created_files(project_dir)
+
+    parts = [output.strip()] if output.strip() else [f"Project '{name}' created."]
+    if files:
+        parts.append("\nCreated files:")
+        for f in files:
+            parts.append(f"  {f}")
+
+    return "\n".join(parts)
+
+
+@tool()
+async def botable_generate(description: str, project_dir: str) -> str:
+    """Generate bot code from a natural-language description.
+
+    Args:
+        description: What the bot should do, e.g.
+                     "echo bot that repeats user messages".
+        project_dir: Absolute path to an existing Botable project directory.
+    """
+    project_dir = os.path.expanduser(project_dir)
+
+    if not os.path.isdir(project_dir):
+        return f"Error: project directory does not exist: {project_dir}"
+
+    output = await run_botable(["generate", description], cwd=project_dir)
+    return output
+
+
+@tool()
+async def botable_templates() -> str:
+    """List available Botable bot templates."""
+    output = await run_botable(["templates"])
+    return output
+
+
+@tool()
+async def botable_dev(project_dir: str) -> str:
+    """Start a bot locally in the background.
+
+    Args:
+        project_dir: Absolute path to the Botable project to run.
+
+    Returns a message with the background process PID so you can stop it later.
+    """
+    project_dir = os.path.expanduser(project_dir)
+
+    if not os.path.isdir(project_dir):
+        return f"Error: project directory does not exist: {project_dir}"
+
+    try:
+        proc = subprocess.Popen(
+            _botable_command() + ["dev"],
+            cwd=project_dir,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            start_new_session=True,  # detach from this process group
+        )
+    except FileNotFoundError as exc:
+        return f"Error: {exc}"
+
+    return (
+        f"Bot dev server started (PID {proc.pid}).\n"
+        f"Working directory: {project_dir}\n"
+        f"To stop: kill {proc.pid}"
+    )
+
+
+@tool()
+async def botable_deploy(project_dir: str) -> str:
+    """Deploy a Botable project; return JSON with project_id, state, and message.
+
+    The CLI uploads the project's .env file with its other project files.
+    """
+    project_dir = os.path.expanduser(project_dir)
+    if not os.path.isdir(project_dir):
+        return f"Error: project directory does not exist: {project_dir}"
+    return await run_botable(["deploy", "--json"], cwd=project_dir)
+
+
+@tool()
+async def botable_bots_list() -> str:
+    """List the authenticated user's deployed bots as JSON."""
+    return await run_botable(["bots", "list", "--json"])
+
+
+@tool()
+async def botable_bot_status(project_id: str) -> str:
+    """Get a bot's current state and running status as a JSON snapshot."""
+    return await run_botable(["logs", project_id, "--json"])
+
+
+@tool()
+async def botable_bot_logs(project_id: str) -> str:
+    """Get the API's status snapshot; runtime log lines are not available yet."""
+    return await run_botable(["logs", project_id, "--json"])
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def main():
+    if mcp is None:
+        raise SystemExit("MCP dependency missing. Install botable-dev[mcp] in this Python environment.")
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()