musigate 0.1.0a2__tar.gz

musigate-0.1.0a2/LICENSE

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

musigate-0.1.0a2/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: musigate
+Version: 0.1.0a2
+Summary: YAML-driven Telegram Bot orchestration engine for automated interactions
+Author: musigate contributors
+License: MIT
+Project-URL: Homepage, https://github.com/opxqo/musigate
+Project-URL: Repository, https://github.com/opxqo/musigate
+Project-URL: Issues, https://github.com/opxqo/musigate/issues
+Keywords: telegram,telegram-bot,music-download,yaml,cli,bot-automation,orchestration
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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 :: Multimedia :: Sound/Audio
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: telethon>=1.33.0
+Requires-Dist: PySocks>=1.7.1
+Requires-Dist: typer>=0.9.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: rich>=13.7.0
+Requires-Dist: aiofiles>=23.2.1
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pydantic>=2.5.3
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.3; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.2; extra == "dev"
+Dynamic: license-file
+
+# musigate
+
+[English](#english) | [中文](#中文)
+
+## English
+
+`musigate` is a Python CLI for searching and downloading music through Telegram bots with a YAML-driven adapter system.
+
+This release is an alpha build. The core CLI flow is working, but bot behavior still depends on upstream Telegram bots and may change over time.
+
+### Install
+
+From a published package:
+
+```bash
+pip install musigate
+```
+
+From a local wheel:
+
+```bash
+pip install dist/musigate-0.1.0a2-py3-none-any.whl
+```
+
+For development:
+
+```bash
+pip install -e .[dev]
+```
+
+### Setup
+
+Copy `.env.example` to `.env`, then fill in your Telegram API credentials:
+
+```bash
+cp .env.example .env
+```
+
+Required values:
+
+- `TELEGRAM_API_ID`
+- `TELEGRAM_API_HASH`
+
+### Built-in Bots
+
+- `music163`
+- `music_v1`
+
+### Agent Skills
+
+The repository now includes a local [skills](skills) directory for agent ecosystems such as Codex or OpenClaw.
+
+Current skills:
+
+- [skills/musigate-cli](skills/musigate-cli)
+- [skills/add-bot-adapter](skills/add-bot-adapter)
+
+### Usage
+
+Login to Telegram:
+
+```bash
+musigate login
+```
+
+Search only:
+
+```bash
+musigate search "Numb" --bot music163
+```
+
+Download with smart matching:
+
+```bash
+musigate download "Numb" --bot music163
+```
+
+Download a specific numbered search result:
+
+```bash
+musigate download "海底" --bot music_v1 --pick 2
+```
+
+Write files to a custom directory:
+
+```bash
+musigate download "海底" --bot music_v1 --pick 2 --output ./downloads/favorites
+```
+
+Machine-readable JSON output:
+
+```bash
+musigate search "Numb" --bot music163 --json
+musigate download "Numb" --bot music163 --json
+musigate list-bots --json
+```
+
+Normal CLI downloads show periodic progress updates including speed and ETA.
+
+## 中文
+
+`musigate` 是一个 Python 命令行工具，用来通过 Telegram 机器人搜索和下载音乐，核心采用 YAML 驱动的适配器架构。
+
+当前版本是 alpha 初版。CLI 主流程已经可用，但具体机器人的行为仍依赖上游 Telegram 机器人，后续可能会变化。
+
+### 安装
+
+从已发布的包安装：
+
+```bash
+pip install musigate
+```
+
+从本地 wheel 安装：
+
+```bash
+pip install dist/musigate-0.1.0a2-py3-none-any.whl
+```
+
+开发模式安装：
+
+```bash
+pip install -e .[dev]
+```
+
+### 配置
+
+把 `.env.example` 复制为 `.env`，然后填入你的 Telegram API 凭据：
+
+```bash
+cp .env.example .env
+```
+
+必填项：
+
+- `TELEGRAM_API_ID`
+- `TELEGRAM_API_HASH`
+
+### 内置 Bot
+
+- `music163`
+- `music_v1`
+
+### 智能体 Skills
+
+仓库根目录新增了一个本地 [skills](skills) 目录，方便 Codex、OpenClaw 这类智能体快速接入。
+
+当前提供：
+
+- [skills/musigate-cli](skills/musigate-cli)
+- [skills/add-bot-adapter](skills/add-bot-adapter)
+
+### 使用方式
+
+登录 Telegram：
+
+```bash
+musigate login
+```
+
+仅搜索，不下载：
+
+```bash
+musigate search "Numb" --bot music163
+```
+
+按智能匹配下载：
+
+```bash
+musigate download "Numb" --bot music163
+```
+
+按搜索结果编号精确下载：
+
+```bash
+musigate download "海底" --bot music_v1 --pick 2
+```
+
+下载到自定义目录：
+
+```bash
+musigate download "海底" --bot music_v1 --pick 2 --output ./downloads/favorites
+```
+
+输出机器可读 JSON：
+
+```bash
+musigate search "Numb" --bot music163 --json
+musigate download "Numb" --bot music163 --json
+musigate list-bots --json
+```
+
+普通 CLI 下载模式会定期显示进度、速度和预计剩余时间。

musigate-0.1.0a2/README.md

@@ -0,0 +1,193 @@
+# musigate
+
+[English](#english) | [中文](#中文)
+
+## English
+
+`musigate` is a Python CLI for searching and downloading music through Telegram bots with a YAML-driven adapter system.
+
+This release is an alpha build. The core CLI flow is working, but bot behavior still depends on upstream Telegram bots and may change over time.
+
+### Install
+
+From a published package:
+
+```bash
+pip install musigate
+```
+
+From a local wheel:
+
+```bash
+pip install dist/musigate-0.1.0a2-py3-none-any.whl
+```
+
+For development:
+
+```bash
+pip install -e .[dev]
+```
+
+### Setup
+
+Copy `.env.example` to `.env`, then fill in your Telegram API credentials:
+
+```bash
+cp .env.example .env
+```
+
+Required values:
+
+- `TELEGRAM_API_ID`
+- `TELEGRAM_API_HASH`
+
+### Built-in Bots
+
+- `music163`
+- `music_v1`
+
+### Agent Skills
+
+The repository now includes a local [skills](skills) directory for agent ecosystems such as Codex or OpenClaw.
+
+Current skills:
+
+- [skills/musigate-cli](skills/musigate-cli)
+- [skills/add-bot-adapter](skills/add-bot-adapter)
+
+### Usage
+
+Login to Telegram:
+
+```bash
+musigate login
+```
+
+Search only:
+
+```bash
+musigate search "Numb" --bot music163
+```
+
+Download with smart matching:
+
+```bash
+musigate download "Numb" --bot music163
+```
+
+Download a specific numbered search result:
+
+```bash
+musigate download "海底" --bot music_v1 --pick 2
+```
+
+Write files to a custom directory:
+
+```bash
+musigate download "海底" --bot music_v1 --pick 2 --output ./downloads/favorites
+```
+
+Machine-readable JSON output:
+
+```bash
+musigate search "Numb" --bot music163 --json
+musigate download "Numb" --bot music163 --json
+musigate list-bots --json
+```
+
+Normal CLI downloads show periodic progress updates including speed and ETA.
+
+## 中文
+
+`musigate` 是一个 Python 命令行工具，用来通过 Telegram 机器人搜索和下载音乐，核心采用 YAML 驱动的适配器架构。
+
+当前版本是 alpha 初版。CLI 主流程已经可用，但具体机器人的行为仍依赖上游 Telegram 机器人，后续可能会变化。
+
+### 安装
+
+从已发布的包安装：
+
+```bash
+pip install musigate
+```
+
+从本地 wheel 安装：
+
+```bash
+pip install dist/musigate-0.1.0a2-py3-none-any.whl
+```
+
+开发模式安装：
+
+```bash
+pip install -e .[dev]
+```
+
+### 配置
+
+把 `.env.example` 复制为 `.env`，然后填入你的 Telegram API 凭据：
+
+```bash
+cp .env.example .env
+```
+
+必填项：
+
+- `TELEGRAM_API_ID`
+- `TELEGRAM_API_HASH`
+
+### 内置 Bot
+
+- `music163`
+- `music_v1`
+
+### 智能体 Skills
+
+仓库根目录新增了一个本地 [skills](skills) 目录，方便 Codex、OpenClaw 这类智能体快速接入。
+
+当前提供：
+
+- [skills/musigate-cli](skills/musigate-cli)
+- [skills/add-bot-adapter](skills/add-bot-adapter)
+
+### 使用方式
+
+登录 Telegram：
+
+```bash
+musigate login
+```
+
+仅搜索，不下载：
+
+```bash
+musigate search "Numb" --bot music163
+```
+
+按智能匹配下载：
+
+```bash
+musigate download "Numb" --bot music163
+```
+
+按搜索结果编号精确下载：
+
+```bash
+musigate download "海底" --bot music_v1 --pick 2
+```
+
+下载到自定义目录：
+
+```bash
+musigate download "海底" --bot music_v1 --pick 2 --output ./downloads/favorites
+```
+
+输出机器可读 JSON：
+
+```bash
+musigate search "Numb" --bot music163 --json
+musigate download "Numb" --bot music163 --json
+musigate list-bots --json
+```
+
+普通 CLI 下载模式会定期显示进度、速度和预计剩余时间。

musigate-0.1.0a2/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "musigate"
+dynamic = ["version"]
+description = "YAML-driven Telegram Bot orchestration engine for automated interactions"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "musigate contributors" }
+]
+requires-python = ">=3.10"
+keywords = [
+    "telegram",
+    "telegram-bot",
+    "music-download",
+    "yaml",
+    "cli",
+    "bot-automation",
+    "orchestration",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Communications :: Chat",
+    "Topic :: Multimedia :: Sound/Audio",
+    "Typing :: Typed",
+]
+dependencies = [
+    "telethon>=1.33.0",
+    "PySocks>=1.7.1",
+    "typer>=0.9.0",
+    "pyyaml>=6.0.1",
+    "rich>=13.7.0",
+    "aiofiles>=23.2.1",
+    "python-dotenv>=1.0.0",
+    "pydantic>=2.5.3"
+]
+
+[project.urls]
+Homepage = "https://github.com/opxqo/musigate"
+Repository = "https://github.com/opxqo/musigate"
+Issues = "https://github.com/opxqo/musigate/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.3",
+    "pytest-asyncio>=0.23.2"
+]
+
+[project.scripts]
+musigate = "musigate.cli:app"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = { attr = "musigate.__version__" }
+
+[tool.setuptools.package-data]
+"musigate.resources" = ["bots/*.yaml", "config/*.yaml"]

musigate-0.1.0a2/setup.cfg

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

musigate-0.1.0a2/src/musigate/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0a2"

musigate-0.1.0a2/src/musigate/adapters/loader.py

@@ -0,0 +1,149 @@
+from importlib import resources
+from importlib.resources.abc import Traversable
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import yaml
+from pydantic import BaseModel, Field
+
+
+class Step(BaseModel):
+    action: str
+    content: Optional[str] = None
+    expect: Optional[str] = None
+    timeout: Optional[int] = None
+    strategy: Optional[str] = None
+    query: Optional[str] = None
+    output: Optional[str] = None
+    cases: Optional[List[Dict[str, Any]]] = None
+    extract: Optional[Dict[str, str]] = None
+    message: Optional[str] = None
+
+
+class CommandDef(BaseModel):
+    steps: List[Step]
+
+
+class BotSettings(BaseModel):
+    timeout: int = 15
+    retry: int = 2
+
+
+class BotConfig(BaseModel):
+    name: str
+    bot_username: str
+    description: str = ""
+    version: str = "1.0"
+    settings: BotSettings = Field(default_factory=BotSettings)
+    commands: Dict[str, CommandDef]
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[3]
+RESOURCE_PACKAGE = "musigate.resources"
+
+
+def _bot_filename(bot_name: str) -> str:
+    return bot_name if bot_name.endswith(".yaml") else f"{bot_name}.yaml"
+
+
+def _dedupe_paths(paths: list[Path]) -> list[Path]:
+    unique_paths: list[Path] = []
+    seen: set[str] = set()
+    for path in paths:
+        key = str(path.expanduser().resolve(strict=False)).lower()
+        if key in seen:
+            continue
+        seen.add(key)
+        unique_paths.append(path)
+    return unique_paths
+
+
+def _external_bot_dirs() -> list[Path]:
+    return _dedupe_paths(
+        [
+            Path.cwd() / "bots",
+            PROJECT_ROOT / "bots",
+        ]
+    )
+
+
+def _explicit_bot_candidates(bot_name: str) -> list[Path]:
+    candidate = Path(bot_name).expanduser()
+    candidates: list[Path] = []
+
+    if candidate.is_absolute() or candidate.parent != Path("."):
+        candidates.append(candidate if candidate.is_absolute() else (Path.cwd() / candidate))
+    elif candidate.suffix == ".yaml":
+        candidates.extend(
+            [
+                Path.cwd() / candidate,
+                PROJECT_ROOT / candidate,
+            ]
+        )
+
+    return _dedupe_paths(candidates)
+
+
+def _packaged_bot_resource(filename: str) -> Traversable | None:
+    resource = resources.files(RESOURCE_PACKAGE).joinpath("bots", filename)
+    return resource if resource.is_file() else None
+
+
+def _read_yaml(source: Path | Traversable) -> dict:
+    if isinstance(source, Path):
+        raw = source.read_text(encoding="utf-8")
+    else:
+        raw = source.read_text(encoding="utf-8")
+    return yaml.safe_load(raw) or {}
+
+
+def _resolve_bot_source(bot_name: str) -> Path | Traversable:
+    for candidate in _explicit_bot_candidates(bot_name):
+        if candidate.is_file():
+            return candidate
+
+    filename = _bot_filename(bot_name)
+    for directory in _external_bot_dirs():
+        candidate = directory / filename
+        if candidate.is_file():
+            return candidate
+
+    packaged = _packaged_bot_resource(filename)
+    if packaged is not None:
+        return packaged
+
+    searched = [str(path) for path in _explicit_bot_candidates(bot_name)]
+    searched.extend(str(directory / filename) for directory in _external_bot_dirs())
+    raise FileNotFoundError(f"Bot config not found: {filename}. Searched: {', '.join(searched)}")
+
+
+def load_bot(bot_name: str) -> dict:
+    """Load and validate a bot configuration."""
+    data = _read_yaml(_resolve_bot_source(bot_name))
+    config = BotConfig(**data)
+    return config.model_dump()
+
+
+def list_bots() -> list[dict]:
+    configs: list[dict] = []
+    seen_names: set[str] = set()
+
+    for directory in _external_bot_dirs():
+        if not directory.exists():
+            continue
+        for bot_file in sorted(directory.glob("*.yaml")):
+            if bot_file.name == "template.yaml" or bot_file.name in seen_names:
+                continue
+            configs.append(load_bot(str(bot_file)))
+            seen_names.add(bot_file.name)
+
+    packaged_dir = resources.files(RESOURCE_PACKAGE).joinpath("bots")
+    for bot_file in sorted(packaged_dir.iterdir(), key=lambda item: item.name):
+        if not bot_file.is_file() or not bot_file.name.endswith(".yaml"):
+            continue
+        if bot_file.name == "template.yaml" or bot_file.name in seen_names:
+            continue
+        configs.append(load_bot(bot_file.name))
+        seen_names.add(bot_file.name)
+
+    return configs