bykcli 1.0.0a1__py3-none-any.whl

bykcli/__init__.py

@@ -0,0 +1,3 @@
+"""bykcli 包入口。"""
+
+__version__ = "1.0.0a1"

bykcli/__main__.py

@@ -0,0 +1,7 @@
+"""支持 ``python -m bykcli`` 运行。"""
+
+from bykcli.main import main
+
+
+if __name__ == "__main__":
+    main()

bykcli/api/__init__.py

@@ -0,0 +1,38 @@
+"""面向子命令和插件的公开运行时 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
+from bykcli.infra.daemon import start_daemon
+
+__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",
+    # 守护进程
+    "start_daemon",
+]

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/api/network.py

@@ -0,0 +1,82 @@
+"""网络工具函数。"""
+
+import socket
+import psutil
+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 地址信息。"""
+    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/api/paths.py

@@ -0,0 +1,31 @@
+"""路径展示注册与渲染。"""
+
+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)),
+        ("Alias File", str(context.paths.alias_file)),
+        ("Logs Directory", str(context.paths.logs_dir)),
+    ]

bykcli/app.py

@@ -0,0 +1,181 @@
+"""CLI 应用装配。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import click
+
+from bykcli.core.context import AppContext
+from bykcli.infra.aliases import AliasAwareGroup
+from bykcli.infra.daemon import kill_daemon_callback
+from bykcli.infra.logging import setup_logging
+from bykcli.infra.registry import register_builtin_plugins, register_plugins
+from bykcli.infra.view import render_dashboard
+from bykcli.runtime import build_runtime
+import bykcli.plugins as builtin_plugins
+
+
+@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.infra.view import format_version_line
+    from rich.console import Console
+
+    app_context: AppContext = ctx.obj.context if ctx.obj else build_runtime()
+    console = Console()
+    console.print(format_version_line(app_context.environment))
+    ctx.exit()
+
+
+def list_plugins_callback(
+    ctx: click.Context,
+    _param: click.Parameter,
+    value: bool,
+) -> None:
+    """List all external plugins and their versions."""
+    if not value or ctx.resilient_parsing:
+        return
+
+    from importlib.metadata import entry_points, version, PackageNotFoundError, distributions
+    from rich.console import Console
+    from rich.table import Table
+    from rich import box
+
+    console = Console()
+    
+    try:
+        plugin_entries = entry_points(group="bykcli.plugins")
+    except TypeError:
+        plugin_entries = entry_points().get("bykcli.plugins", [])
+
+    if not plugin_entries:
+        console.print("[dim]No external plugins installed.[/dim]")
+        ctx.exit()
+
+    table = Table(
+        title="[bold cyan]External Plugins[/bold cyan]",
+        box=box.ROUNDED,
+        border_style="bright_blue",
+        header_style="bold bright_magenta",
+        show_lines=True,
+        padding=(0, 2),
+        collapse_padding=False,
+    )
+    table.add_column("Package Name", style="bold cyan", no_wrap=True)
+    table.add_column("Version", style="bold green", justify="center")
+    table.add_column("Entry Point", style="dim", overflow="fold")
+
+    for entry in plugin_entries:
+        pkg_name = entry.name
+        pkg_version = "unknown"
+        
+        candidates = [entry.name]
+        
+        if entry.name.startswith("bykcli"):
+            candidates.append(f"bykcli-{entry.name[5:]}")
+        else:
+            candidates.append(f"bykcli-{entry.name}")
+        
+        candidates.append(entry.name.replace("-", "_"))
+        candidates.append(entry.name.replace("_", "-"))
+        
+        try:
+            module_path = entry.value.split(":")[0]
+            top_level_pkg = module_path.split(".")[0]
+            candidates.append(top_level_pkg)
+            if not top_level_pkg.startswith("bykcli"):
+                candidates.append(f"bykcli-{top_level_pkg}")
+        except (IndexError):
+            pass
+        
+        found = False
+        for candidate in candidates:
+            if not candidate:
+                continue
+            try:
+                pkg_version = version(candidate)
+                pkg_name = candidate
+                found = True
+                break
+            except PackageNotFoundError:
+                continue
+        
+        table.add_row(pkg_name, pkg_version, entry.value)
+
+    click.echo()
+    console.print(table)
+    click.echo()
+    ctx.exit()
+
+
+def create_cli() -> click.Group:
+    """创建根 CLI 对象。"""
+
+    runtime: AppContext | None = None
+
+    def get_runtime() -> AppContext:
+        nonlocal runtime
+        if runtime is None:
+            runtime = build_runtime()
+        return runtime
+
+    temp_runtime = build_runtime()
+    setup_logging(temp_runtime)
+
+    @click.group(
+        cls=AliasAwareGroup,
+        context_settings={"help_option_names": ["-h", "--help"]},
+        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.option(
+        "--kill",
+        "-k",
+        type=str,
+        callback=kill_daemon_callback,
+        expose_value=False,
+        is_eager=True,
+        help='Kill background daemon processes. Use "all" to kill all or specify PID.',
+    )
+    @click.option(
+        "--list",
+        "-l",
+        is_flag=True,
+        callback=list_plugins_callback,
+        expose_value=False,
+        is_eager=True,
+        help="List all external plugins and their versions.",
+    )
+    @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:
+            render_dashboard(ctx.obj.context, cli)
+
+    cli.runtime_provider = get_runtime
+    register_builtin_plugins(cli, builtin_plugins)
+    register_plugins(cli)
+    return cli

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/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

bykcli/core/environment.py

@@ -0,0 +1,29 @@
+"""运行环境信息。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import platform
+import sys
+
+
+@dataclass(slots=True)
+class EnvironmentInfo:
+    """CLI 运行环境信息。"""
+
+    app_name: str
+    version: str
+    python_version: str
+    executable: str
+    platform_name: str
+
+
+def collect_environment(app_name: str, version: str) -> EnvironmentInfo:
+    """收集当前运行环境。"""
+    return EnvironmentInfo(
+        app_name=app_name,
+        version=version,
+        python_version=platform.python_version(),
+        executable=sys.executable,
+        platform_name=platform.platform(),
+    )

bykcli/core/errors.py

@@ -0,0 +1,7 @@
+"""统一异常定义。"""
+
+from __future__ import annotations
+
+
+class CliError(RuntimeError):
+    """面向终端用户的业务异常。"""

bykcli/core/persistence.py

@@ -0,0 +1,54 @@
+"""持久化路径布局。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(slots=True)
+class PathLayout:
+    """持久化目录布局数据结构。"""
+
+    root_dir: Path
+    state_dir: Path
+    logs_dir: Path
+    runtime_dir: Path
+    alias_file: Path
+    app_log_file: Path
+    daemon_dir: Path
+
+    @staticmethod
+    def _validate_safe_name(value: str, field_name: str) -> str:
+        """校验名称安全性，防止路径穿越和脏数据文件名。"""
+        normalized = value.strip()
+        if not normalized:
+            raise ValueError(f"{field_name} 不能为空")
+        if normalized in {".", ".."}:
+            raise ValueError(f"{field_name} 不能为 '.' 或 '..'")
+        if "/" in normalized or "\\" in normalized:
+            raise ValueError(f"{field_name} 不能包含路径分隔符")
+        return normalized
+
+    def command_state_dir(self, command_name: str) -> Path:
+        """返回子命令专属目录。"""
+        safe_command_name = self._validate_safe_name(command_name, "command_name")
+        path = self.state_dir / safe_command_name
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+
+    def command_state_file(self, command_name: str, *parts: str) -> Path:
+        """返回子命令专属文件路径。"""
+        target = self.command_state_dir(command_name)
+        for part in parts:
+            safe_part = self._validate_safe_name(part, "part")
+            target = target / safe_part
+        target.parent.mkdir(parents=True, exist_ok=True)
+        return target
+
+    def state_file(self, name: str) -> Path:
+        """返回应用级状态文件路径。"""
+        safe_name = self._validate_safe_name(name, "name")
+        path = self.state_dir / f"{safe_name}.json"
+        path.parent.mkdir(parents=True, exist_ok=True)
+        return path

bykcli/core/state.py

@@ -0,0 +1,20 @@
+"""子命令状态存储协议。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Protocol
+
+
+class StateStore(Protocol):
+    """状态存储协议。"""
+
+    path: Path
+
+    def load(self) -> dict[str, Any]: ...
+    def save(self, data: dict[str, Any]) -> dict[str, Any]: ...
+    def get(self, key: str, default: Any = None) -> Any: ...
+    def set(self, key: str, value: Any) -> dict[str, Any]: ...
+    def update(self, values: dict[str, Any]) -> dict[str, Any]: ...
+    def delete(self, key: str) -> dict[str, Any]: ...
+    def clear(self) -> dict[str, Any]: ...