bykcli 1.0.0a1__tar.gz

bykcli-1.0.0a1/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-1.0.0a1/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: bykcli
+Version: 1.0.0a1
+Summary: A lightweight, extensible collection of CLI utilities
+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: psutil>=5.9.0
+Requires-Dist: rich>=10.0.0
+Provides-Extra: dev
+Requires-Dist: pytest<8.0.0,>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov<5.0.0,>=4.0.0; extra == "dev"
+Requires-Dist: commitizen; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+## 简介
+
+<p>
+  <img src="https://img.shields.io/badge/python-%E2%89%A53.10-blue?logo=python&logoColor=white" />
+  <img src="https://img.shields.io/github/license/fcbyk/bykcli.svg" />
+  <img src="https://github.com/fcbyk/bykcli/actions/workflows/test.yml/badge.svg" />
+  <img src="https://codecov.io/gh/fcbyk/bykcli/branch/main/graph/badge.svg" />
+</p>
+
+**`bykcli`** 是一个轻量的命令行工具集合 🧰
+
+用于通过简单命令解决一些日常的小需求。
+
+比如：
+* 没有现成工具可用
+* 或者工具太重、不够直接
+* 想一条命令快速搞定
+
+项目采用插件化结构，子命令以插件形式组织，支持按需插拔

bykcli-1.0.0a1/README.md

@@ -0,0 +1,19 @@
+## 简介
+
+<p>
+  <img src="https://img.shields.io/badge/python-%E2%89%A53.10-blue?logo=python&logoColor=white" />
+  <img src="https://img.shields.io/github/license/fcbyk/bykcli.svg" />
+  <img src="https://github.com/fcbyk/bykcli/actions/workflows/test.yml/badge.svg" />
+  <img src="https://codecov.io/gh/fcbyk/bykcli/branch/main/graph/badge.svg" />
+</p>
+
+**`bykcli`** 是一个轻量的命令行工具集合 🧰
+
+用于通过简单命令解决一些日常的小需求。
+
+比如：
+* 没有现成工具可用
+* 或者工具太重、不够直接
+* 想一条命令快速搞定
+
+项目采用插件化结构，子命令以插件形式组织，支持按需插拔

bykcli-1.0.0a1/pyproject.toml

@@ -0,0 +1,94 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bykcli"
+dynamic = ["version", "readme"]
+description = "A lightweight, extensible collection of CLI utilities"
+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",
+    "psutil>=5.9.0",
+    "rich>=10.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0,<8.0.0",
+    "pytest-cov>=4.0.0,<5.0.0",
+    "commitizen",
+    "build",
+    "twine",
+]
+
+[project.scripts]
+fcbyk = "bykcli.main:main"
+byk = "bykcli.main:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+packages = { find = { where = ["src"], include = ["bykcli*"], exclude = ["example*"] } }
+
+[tool.setuptools.dynamic]
+version = {attr = "bykcli.__version__"}
+readme = {file = ["README.md"], content-type = "text/markdown"}
+
+[tool.pytest.ini_options]
+testpaths = ["src/bykcli/tests"]
+python_files = ["test_*.py"]
+addopts = "-v --cov=bykcli --cov-report=term-missing"
+norecursedirs = ["example", "example-*", ".git", "dist", "build"]
+
+[tool.commitizen]
+name = "cz_customize"
+version = "1.0.0a1"
+tag_format = "v$version"
+changelog_file = "CHANGELOG.md"
+bump_message = "release: v$new_version"
+version_files = [
+    "src/bykcli/__init__.py:__version__",
+    "pyproject.toml:version ="
+]
+
+[tool.commitizen.customize]
+commit_parser = '^(?P<change_type>feat|fix|refactor|docs|perf|test|style|chore)(?:\((?P<scope>[^\)]+)\))?:\s*(?P<message>.+)$'
+changelog_pattern = '^(feat|fix|refactor|docs|perf|test|style|chore)'
+change_type_order = [
+    "feat",
+    "fix",
+    "refactor",
+    "docs",
+    "style",
+    "perf",
+    "test",
+    "chore"
+]
+
+message_template = """
+{{ change_type }}{% if scope %}({{ scope }}){% endif %}: {{ message }}
+"""
+
+[tool.commitizen.customize.change_type_map]
+feat = "Features"
+fix = "Bug Fixes"
+refactor = "Refactor"
+docs = "Documentation"
+style = "Styles"
+perf = "Performance"
+test = "Tests"
+chore = "Chores"

bykcli-1.0.0a1/setup.cfg

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

bykcli-1.0.0a1/src/bykcli/__init__.py

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

bykcli-1.0.0a1/src/bykcli/__main__.py

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

bykcli-1.0.0a1/src/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-1.0.0a1/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-1.0.0a1/src/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-1.0.0a1/src/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-1.0.0a1/src/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-1.0.0a1/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-1.0.0a1/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