bykcli-plugin 1.0.0a5__tar.gz

bykcli_plugin-1.0.0a5/LICENSE

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

bykcli_plugin-1.0.0a5/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: bykcli-plugin
+Version: 1.0.0a5
+Summary: Plugin infrastructure for bykcli
+Author-email: fcbyk <731240932@qq.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0.0
+Requires-Dist: bykcli<2.0,>=1.0.0a5
+Provides-Extra: test
+Requires-Dist: pytest<8.0.0,>=7.0.0; extra == "test"
+Requires-Dist: pytest-cov<5.0.0,>=4.0.0; extra == "test"
+Provides-Extra: build
+Requires-Dist: commitizen; extra == "build"
+Requires-Dist: build; extra == "build"
+Requires-Dist: twine; extra == "build"
+Dynamic: license-file
+
+# bykcli-plugin
+
+[![Python](https://img.shields.io/badge/python-%E2%89%A53.10-blue?logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![Tests](https://github.com/fcbyk/bykcli/actions/workflows/test.yml/badge.svg)](https://github.com/fcbyk/bykcli/actions/workflows/test.yml)
+[![Coverage](https://codecov.io/gh/fcbyk/bykcli/branch/main/graph/badge.svg)](https://codecov.io/gh/fcbyk/bykcli)
+[![License](https://img.shields.io/github/license/fcbyk/bykcli.svg)](https://github.com/fcbyk/bykcli/blob/main/LICENSE)
+
+Plugin infrastructure for [bykcli](https://github.com/fcbyk/bykcli).
+
+## Install
+
+```bash
+pip install bykcli-plugin
+```
+
+## Usage
+
+Implement `PluginProtocol` and register your commands:
+
+```python
+# my_plugin.py
+import click
+from bykcli import PluginProtocol
+
+class MyPlugin(PluginProtocol):
+    commands = {"hello": "say hello"}
+
+    def register(self, cli: click.Group) -> None:
+        @cli.command()
+        @click.pass_context
+        def hello(ctx):
+            click.echo("Hello from my plugin!")
+```
+
+## API
+
+- **PluginProtocol** — class-based plugin registration protocol
+- **CommandContext / pass_command_context / get_app_context** — command runtime context
+- **PathItem / PathProvider / register_path_provider** — path management
+- **get_private_networks / ensure_port_available** — network utilities
+- **StateStore** — persistent key-value storage per command
+
+## License
+
+MIT

bykcli_plugin-1.0.0a5/README.md

@@ -0,0 +1,45 @@
+# bykcli-plugin
+
+[![Python](https://img.shields.io/badge/python-%E2%89%A53.10-blue?logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![Tests](https://github.com/fcbyk/bykcli/actions/workflows/test.yml/badge.svg)](https://github.com/fcbyk/bykcli/actions/workflows/test.yml)
+[![Coverage](https://codecov.io/gh/fcbyk/bykcli/branch/main/graph/badge.svg)](https://codecov.io/gh/fcbyk/bykcli)
+[![License](https://img.shields.io/github/license/fcbyk/bykcli.svg)](https://github.com/fcbyk/bykcli/blob/main/LICENSE)
+
+Plugin infrastructure for [bykcli](https://github.com/fcbyk/bykcli).
+
+## Install
+
+```bash
+pip install bykcli-plugin
+```
+
+## Usage
+
+Implement `PluginProtocol` and register your commands:
+
+```python
+# my_plugin.py
+import click
+from bykcli import PluginProtocol
+
+class MyPlugin(PluginProtocol):
+    commands = {"hello": "say hello"}
+
+    def register(self, cli: click.Group) -> None:
+        @cli.command()
+        @click.pass_context
+        def hello(ctx):
+            click.echo("Hello from my plugin!")
+```
+
+## API
+
+- **PluginProtocol** — class-based plugin registration protocol
+- **CommandContext / pass_command_context / get_app_context** — command runtime context
+- **PathItem / PathProvider / register_path_provider** — path management
+- **get_private_networks / ensure_port_available** — network utilities
+- **StateStore** — persistent key-value storage per command
+
+## License
+
+MIT

bykcli_plugin-1.0.0a5/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=75"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bykcli-plugin"
+version = "1.0.0a5"
+description = "Plugin infrastructure for bykcli"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+    {name = "fcbyk", email = "731240932@qq.com"}
+]
+license = {text = "MIT"}
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "click>=8.0.0",
+    "bykcli>=1.0.0a5,<2.0",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=7.0.0,<8.0.0",
+    "pytest-cov>=4.0.0,<5.0.0",
+]
+build = [
+    "commitizen",
+    "build",
+    "twine",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "-v --cov=bykcli --cov-report=term-missing"
+
+[tool.pyright]
+extraPaths = ["src"]

bykcli_plugin-1.0.0a5/setup.cfg

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

bykcli_plugin-1.0.0a5/src/bykcli/__init__.py

@@ -0,0 +1,5 @@
+from bykcli.core.plugin import PluginProtocol
+
+__version__ = "1.0.0a5"
+
+

bykcli_plugin-1.0.0a5/src/bykcli/__main__.py

@@ -0,0 +1,23 @@
+"""支持 ``python -m bykcli`` 运行。"""
+
+import sys
+
+
+if __name__ == "__main__":
+    # --scan-plugins: Rust 调用的无头模式，仅扫描插件并写缓存，不启动 CLI
+    if len(sys.argv) >= 2 and sys.argv[1] == "--scan-plugins":
+        from pathlib import Path
+
+        from bykcli.infra.cache import _build_cache
+        from bykcli.infra.persistence import write_json
+
+        cache_dir = Path.home() / ".bykcli" / "cache"
+        cache_dir.mkdir(parents=True, exist_ok=True)
+
+        data = _build_cache()
+        write_json(cache_dir / "app.json", data)
+        sys.exit(0)
+
+    from bykcli.app import create_cli
+
+    create_cli()()

bykcli_plugin-1.0.0a5/src/bykcli/api/__init__.py

@@ -0,0 +1,35 @@
+"""面向子命令和插件的公开运行时 API。"""
+
+from bykcli.api.context import CommandContext, pass_command_context, get_app_context
+from bykcli.api.paths import (
+    PathItem,
+    PathProvider,
+    register_path_provider,
+    get_path_provider,
+    global_path_items,
+)
+
+from bykcli.api.network import (
+    get_private_networks,
+    ensure_port_available,
+)
+
+from bykcli.core.state import StateStore
+
+__all__ = [
+    # 上下文
+    "CommandContext",
+    "pass_command_context",
+    "get_app_context",
+    # 路径管理
+    "PathItem",
+    "PathProvider",
+    "register_path_provider",
+    "get_path_provider",
+    "global_path_items",
+    # 网络工具
+    "get_private_networks",
+    "ensure_port_available",
+    # 状态存储
+    "StateStore",
+]

bykcli_plugin-1.0.0a5/src/bykcli/api/context.py

@@ -0,0 +1,65 @@
+"""面向子命令的上下文封装。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from functools import update_wrapper
+import logging
+from typing import Any, Callable, TypeVar, cast
+
+import click
+
+from bykcli.app import CliState
+from bykcli.core.context import AppContext, CommandContextLike
+from bykcli.core.state import StateStore
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+@dataclass(slots=True)
+class CommandContext(CommandContextLike):
+    """提供给子命令的便捷上下文。"""
+
+    name: str
+    app: AppContext
+    logger: logging.Logger
+    _state_cache: dict[str, StateStore] = field(default_factory=dict, init=False, repr=False)
+
+    def state(self, name: str = "state") -> StateStore:
+        """获取当前命令的专属存储。"""
+        if name not in self._state_cache:
+            self._state_cache[name] = self.app.command_store(self.name, name)
+        return self._state_cache[name]
+
+def _get_group_name(ctx: click.Context) -> str:
+    """获取二级命令名"""
+    node = ctx
+    while node.parent and node.parent.parent is not None:
+        node = node.parent
+    return node.command.name or "unknown"
+
+def build_command_context(ctx: click.Context) -> CommandContext:
+    """根据当前 Click 上下文构建命令上下文"""
+    state = cast(CliState, ctx.obj)
+    command_name = _get_group_name(ctx)
+    return CommandContext(
+        name=command_name,
+        app=state.context,
+        logger=state.context.get_command_logger(command_name),
+    )
+
+
+def pass_command_context(func: F) -> F:
+    """向子命令注入便捷上下文。"""
+
+    @click.pass_context
+    def new_func(ctx: click.Context, *args: Any, **kwargs: Any) -> Any:
+        return ctx.invoke(func, build_command_context(ctx), *args, **kwargs)
+
+    return cast(F, update_wrapper(new_func, func))
+
+
+def get_app_context() -> AppContext:
+    """获取当前应用上下文。"""
+    from bykcli.runtime import build_runtime
+    return build_runtime()

bykcli_plugin-1.0.0a5/src/bykcli/api/network.py

@@ -0,0 +1,91 @@
+"""网络工具函数。"""
+import socket
+from typing import List, Dict
+
+
+# 网络接口分类规则：(关键词列表，类型名称，是否虚拟接口，优先级)
+IFACE_RULES = [
+    (['vmware', 'vmnet'],         'vmware',     True,  30),
+    (['vbox', 'virtualbox'],      'virtualbox', True,  30),
+    (['docker', 'wsl'],           'container',  True,  40),
+    (['bluetooth'],               'bluetooth',  True,  60),
+    (['ethernet', '以太网'],       'ethernet',   False, 10),
+    (['wlan', 'wi-fi', '无线'],   'wifi',       False, 10),
+    (['loopback'],                'loopback',   True,  100),
+]
+
+
+def detect_iface_type(iface: str) -> tuple[str, bool, int]:
+    """检测网络接口类型。"""
+    lname = iface.lower()
+    for keywords, t, virtual, prio in IFACE_RULES:
+        if any(k in lname for k in keywords):
+            return t, virtual, prio
+    return 'unknown', False, 50
+
+
+def get_private_networks() -> List[Dict]:
+    """获取所有局域网 IP 地址信息。"""
+    try:
+        import psutil
+    except ImportError:
+        return [{
+            "iface": "localhost",
+            "ips": ["127.0.0.1"],
+            "type": "loopback",
+            "virtual": True,
+            "priority": 100
+        }]
+
+    results = []
+    interfaces = psutil.net_if_addrs()
+
+    for iface, addrs in interfaces.items():
+        ips = []
+        iface_type, is_virtual, priority = detect_iface_type(iface)
+
+        for addr in addrs:
+            if addr.family != socket.AF_INET:
+                continue
+
+            ip = addr.address
+
+            # 跳过回环地址和链路本地地址
+            if ip.startswith('127.'):
+                continue
+            if ip.startswith('169.254.'):
+                continue
+            # 只保留私有 IP 地址
+            if ip.startswith(('10.', '192.168.', '172.')):
+                ips.append(ip)
+
+        if ips:
+            results.append({
+                "iface": iface,
+                "ips": ips,
+                "type": iface_type,
+                "virtual": is_virtual,
+                "priority": priority
+            })
+
+    # 按优先级排序（数字越小优先级越高）
+    results.sort(key=lambda x: x['priority'])
+    
+    # 如果没有找到任何局域网 IP，返回 localhost
+    if not results:
+        results.append({
+            "iface": "localhost",
+            "ips": ["127.0.0.1"],
+            "type": "loopback",
+            "virtual": True,
+            "priority": 100
+        })
+    
+    return results
+
+
+def ensure_port_available(port: int, host: str = "0.0.0.0") -> None:
+    """检查端口是否可用。"""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        s.bind((host, int(port)))

bykcli_plugin-1.0.0a5/src/bykcli/api/paths.py

@@ -0,0 +1,30 @@
+"""路径展示注册与渲染。"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from bykcli.core.context import AppContext
+
+PathItem = tuple[str, str]
+PathProvider = Callable[[AppContext], list[PathItem]]
+
+_PATH_PROVIDERS: dict[str, PathProvider] = {}
+
+
+def register_path_provider(command_name: str, provider: PathProvider) -> None:
+    """注册子命令路径提供器。"""
+    _PATH_PROVIDERS[command_name] = provider
+
+
+def get_path_provider(command_name: str) -> PathProvider | None:
+    """获取某个子命令的路径提供器。"""
+    return _PATH_PROVIDERS.get(command_name)
+
+
+def global_path_items(context: AppContext) -> list[PathItem]:
+    """返回默认展示的全局路径。"""
+    return [
+        ("CLI Home", str(context.paths.root_dir)),
+        ("Logs Directory", str(context.paths.logs_dir)),
+    ]

bykcli_plugin-1.0.0a5/src/bykcli/app.py

@@ -0,0 +1,151 @@
+"""CLI 应用装配。"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+import click
+
+from bykcli.core.context import AppContext
+from bykcli.core.errors import CliError
+
+logger = logging.getLogger("bykcli")
+
+
+class PluginAwareGroup(click.Group):
+    """支持插件动态加载的命令组。"""
+
+    runtime_provider: Any = None
+
+    def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
+        return super().parse_args(ctx, args)
+
+    def resolve_command(
+        self,
+        ctx: click.Context,
+        args: list[str],
+    ) -> tuple[str | None, click.Command | None, list[str]]:
+        orig_args = list(args)
+        try:
+            return super().resolve_command(ctx, args)
+        except click.UsageError:
+            pass
+
+        if not orig_args:
+            return super().resolve_command(ctx, orig_args)
+
+        context = self._get_context(ctx)
+
+        # 检查缓存中的插件命令，按需加载单个插件
+        from bykcli.infra.cache import load_cache
+        from bykcli.infra.registry import load_single_plugin
+
+        cache_data = load_cache(context.paths.cache_dir / "app.json")
+        if orig_args[0] in cache_data.get("commands", {}):
+            cmd_name = orig_args[0]
+            module_path = cache_data["commands"][cmd_name]["module"]
+            load_single_plugin(self, cmd_name, module_path)
+            return super().resolve_command(ctx, orig_args)
+
+        # 未知命令
+        raise click.UsageError(f"Unknown command: {orig_args[0]}")
+
+    def _get_context(self, ctx: click.Context) -> AppContext:
+        """在命令解析阶段获取运行时上下文。"""
+        if ctx.obj is not None:
+            return ctx.obj.context
+        if callable(self.runtime_provider):
+            return self.runtime_provider()  # type: ignore[return-type]
+        raise click.ClickException("Runtime context not yet initialized")
+
+    def invoke(self, ctx: click.Context) -> Any:
+        """统一兜底未处理异常"""
+        try:
+            return super().invoke(ctx)
+        except click.ClickException:
+            raise
+        except click.exceptions.Exit:
+            raise
+        except CliError as exc:
+            logger.warning("cli error: %s", exc)
+            raise click.ClickException(str(exc)) from exc
+        except SystemExit:
+            raise
+        except Exception as exc:  # noqa: BLE001
+            logger.exception("unexpected cli error")
+            log_file = "log file"
+            try:
+                if ctx.obj and hasattr(ctx.obj, 'context'):
+                    log_file = getattr(ctx.obj.context.paths, 'app_log_file', 'log file')
+            except Exception:
+                pass
+
+            raise click.ClickException(
+                f"Unexpected error occurred, see logs at: {log_file}"
+            ) from exc
+
+
+@dataclass(slots=True)
+class CliState:
+    """Click 根命令共享状态。"""
+
+    context: AppContext
+
+
+def version_callback(
+    ctx: click.Context,
+    _param: click.Parameter,
+    value: bool,
+) -> None:
+    """Show version and exit."""
+    if not value or ctx.resilient_parsing:
+        return
+
+    from bykcli.runtime import build_runtime
+
+    app_context: AppContext = ctx.obj.context if ctx.obj else build_runtime()
+    click.echo(f"v{app_context.version}")
+    ctx.exit()
+
+
+def create_cli() -> click.Group:
+    """创建根 CLI 对象。"""
+
+    from bykcli.runtime import build_runtime
+
+    runtime: AppContext | None = None
+
+    def get_runtime() -> AppContext:
+        nonlocal runtime
+        if runtime is None:
+            runtime = build_runtime()
+        return runtime
+
+    @click.group(
+        cls=PluginAwareGroup,
+        context_settings={"help_option_names": ["-h", "--help"]},
+        add_help_option=False,
+        invoke_without_command=True,
+    )
+    @click.option(
+        "--version",
+        "-v",
+        is_flag=True,
+        callback=version_callback,
+        expose_value=False,
+        is_eager=True,
+        help="Show version and exit.",
+    )
+    @click.pass_context
+    def cli(ctx: click.Context) -> None:
+        ctx.obj = CliState(context=get_runtime())
+        ctx.obj.context.logger.info("BYK CLI v%s started", ctx.obj.context.version)
+        if ctx.invoked_subcommand is None:
+            from bykcli.infra.view import render_dashboard
+
+            render_dashboard(ctx.obj.context, cli)
+
+    cli.runtime_provider = get_runtime
+    return cli

bykcli_plugin-1.0.0a5/src/bykcli/core/__init__.py

@@ -0,0 +1,14 @@
+"""核心能力模块。"""
+
+from bykcli.core.context import AppContext, CommandContextLike
+from bykcli.core.environment import EnvironmentInfo
+from bykcli.core.persistence import PathLayout
+from bykcli.core.state import StateStore
+
+__all__ = [
+    "AppContext",
+    "CommandContextLike",
+    "EnvironmentInfo",
+    "PathLayout",
+    "StateStore",
+]

bykcli_plugin-1.0.0a5/src/bykcli/core/context.py

@@ -0,0 +1,50 @@
+"""CLI 运行时上下文。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import logging
+from typing import TYPE_CHECKING, Protocol
+
+from bykcli.core.environment import EnvironmentInfo
+from bykcli.core.persistence import PathLayout
+
+if TYPE_CHECKING:
+    from bykcli.core.state import StateStore
+
+
+class CommandContextLike(Protocol):
+    """命令上下文协议。"""
+
+    name: str
+    app: "AppContext"
+    logger: logging.Logger
+
+    def state(self, name: str = "state") -> "StateStore": ...
+
+
+@dataclass(slots=True)
+class AppContext:
+    """子命令共享的核心上下文。"""
+
+    app_name: str
+    version: str
+    paths: PathLayout
+    environment: EnvironmentInfo
+    logger: logging.Logger
+
+    def command_store(
+        self,
+        command_name: str,
+        name: str = "state",
+    ) -> StateStore:
+        """返回某个子命令的状态存储。"""
+        raise NotImplementedError
+
+    def store(self, name: str = "byk.config") -> StateStore:
+        """返回应用级共享状态存储。"""
+        raise NotImplementedError
+
+    def get_command_logger(self, command_name: str) -> logging.Logger:
+        """获取命令专属 logger。"""
+        raise NotImplementedError