xb-init 1.3.4__py3-none-any.whl

xb/__init__.py

@@ -0,0 +1,10 @@
+"""
+xb - Project management tool for UV + FastAPI + Vue3 + Electron desktop applications
+"""
+
+from importlib.metadata import PackageNotFoundError, version as _get_version
+
+try:
+    __version__ = _get_version("xb-init")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"

xb/cli.py

@@ -0,0 +1,105 @@
+"""
+xb CLI 入口
+提供项目初始化、开发、构建等命令
+"""
+
+import click
+from rich.console import Console
+
+from . import __version__
+
+from .commands.build import build
+from .commands.dev import dev
+from .commands.doctor import doctor
+from .commands.init import XbGroup, init_command
+from .commands.upgrade import run_upgrade
+from .commands.version import version
+from .utils.version_check import ensure_check, get_pending_upgrade_hint
+
+console = Console()
+COMMAND_ORDER = ["doctor", "init", "dev", "build", "version"]
+
+
+def _format_command_options(cmd: click.Command) -> str:
+    params = []
+    for param in cmd.params:
+        if isinstance(param, click.Argument):
+            if isinstance(param.type, click.Choice):
+                choices = "|".join(param.type.choices)
+                params.append(f"{param.name}: {choices}")
+            else:
+                params.append(param.name)
+            continue
+
+        if not isinstance(param, click.Option):
+            continue
+        if param.name == "help":
+            continue
+
+        option = param.opts[0] if param.opts else param.name
+        if not param.is_flag:
+            metavar = param.metavar or param.name.upper()
+            option = f"{option} {metavar}"
+        params.append(option)
+
+    return ", ".join(params)
+
+
+class ColorfulXbGroup(XbGroup):
+    def list_commands(self, ctx):
+        existing = set(super().list_commands(ctx))
+        ordered = [name for name in COMMAND_ORDER if name in existing]
+        ordered.extend(name for name in super().list_commands(ctx) if name not in ordered)
+        return ordered
+
+    def format_help(self, ctx, formatter):
+        console.print(
+            "\n[bold green]Usage:[/bold green] [cyan]xb [OPTIONS] COMMAND [ARGS]...[/cyan]\n"
+        )
+        console.print("[dim]xb - UV + FastAPI + Vue3 + Electron 桌面应用项目管理工具[/dim]")
+        console.print("[dim]类似 uv，专为 Electron 桌面应用设计。[/dim]\n")
+        console.print("[bold green]Options:[/bold green]")
+        console.print("  [cyan]--version[/cyan]  显示 xb 工具版本号并退出。")
+        console.print("  [cyan]--upgrade[/cyan]  升级 xb 到 PyPI 最新版本并退出。")
+        console.print("  [cyan]-h, --help[/cyan] 显示帮助信息并退出。\n")
+        console.print("[bold green]Commands:[/bold green]")
+        for subcommand in self.list_commands(ctx):
+            cmd = self.get_command(ctx, subcommand)
+            if cmd is None:
+                continue
+            help_text = cmd.get_short_help_str()
+            console.print(f"  [cyan]{subcommand:<10}[/cyan] {help_text}")
+            options = _format_command_options(cmd)
+            if options:
+                console.print(f"  [dim]{'':<10} 参数: {options}[/dim]")
+        console.print()
+
+
+@click.group(cls=ColorfulXbGroup, context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(version=__version__, prog_name="xb")
+@click.option("--upgrade", "upgrade_requested", is_flag=True, is_eager=True, help="升级 xb 到 PyPI 最新版本并退出。")
+def main(upgrade_requested: bool):
+    """
+    xb - UV + FastAPI + Vue3 + Electron 桌面应用项目管理工具
+
+    类似 uv，专为 Electron 桌面应用设计。
+    """
+    if upgrade_requested:
+        run_upgrade()
+        raise click.exceptions.Exit()
+
+    ensure_check(__version__)
+    hint = get_pending_upgrade_hint(__version__)
+    if hint:
+        console.print(f"[yellow]{hint}[/yellow]\n")
+
+
+main.add_command(doctor, name="doctor")
+main.add_command(init_command, name="init")
+main.add_command(dev, name="dev")
+main.add_command(build, name="build")
+main.add_command(version, name="version")
+
+
+if __name__ == "__main__":
+    main()

xb/commands/__init__.py

@@ -0,0 +1 @@
+"""xb commands package"""

xb/commands/build.py

@@ -0,0 +1,78 @@
+"""
+xb build 命令实现
+构建项目
+"""
+
+import subprocess
+from pathlib import Path
+
+import click
+
+from ..utils.click_helpers import ChineseHelpCommand, HELP_CONTEXT
+
+
+def is_project_root(path: Path) -> bool:
+    return (path / "pyproject.toml").exists() and (path / "build.sh").exists()
+
+
+def find_project_root() -> Path | None:
+    cwd = Path.cwd()
+    for path in [cwd] + list(cwd.parents):
+        if is_project_root(path):
+            return path
+    return None
+
+
+def _selected_target(target: str, frontend: bool, backend: bool, electron: bool, all_build: bool) -> str:
+    selected_flags = [
+        ("frontend", frontend),
+        ("backend", backend),
+        ("electron", electron),
+        ("all", all_build),
+    ]
+    selected = [name for name, enabled in selected_flags if enabled]
+    if len(selected) > 1:
+        raise click.UsageError("构建目标只能指定一个")
+    if selected:
+        if target != "all":
+            raise click.UsageError("位置参数和 -a/-f/-b/-e 只能二选一")
+        return selected[0]
+    return target
+
+
+@click.command(cls=ChineseHelpCommand, context_settings=HELP_CONTEXT)
+@click.argument(
+    "target",
+    required=False,
+    default="all",
+    type=click.Choice(["all", "frontend", "backend", "electron"], case_sensitive=False),
+)
+@click.option("-a", "all_build", is_flag=True, default=False, help="构建所有")
+@click.option("-f", "frontend", is_flag=True, default=False, help="只构建前端")
+@click.option("-b", "backend", is_flag=True, default=False, help="只构建后端")
+@click.option("-e", "electron", is_flag=True, default=False, help="只构建 Electron DEB")
+def build(target: str, all_build: bool, frontend: bool, backend: bool, electron: bool):
+    """构建项目
+
+    示例:
+        xb build
+        xb build all
+        xb build frontend
+        xb build backend
+        xb build electron
+        xb build -f
+    """
+    project_root = find_project_root()
+    if not project_root:
+        click.echo("❌ 未找到项目根目录（缺少 pyproject.toml 或 build.sh）")
+        raise click.Abort()
+
+    build_script = project_root / "build.sh"
+    selected = _selected_target(target.lower(), frontend, backend, electron, all_build)
+    arg_map = {
+        "all": "-a",
+        "frontend": "-f",
+        "backend": "-b",
+        "electron": "-e",
+    }
+    subprocess.run(["bash", str(build_script), arg_map[selected]], cwd=project_root)

xb/commands/dev.py

@@ -0,0 +1,48 @@
+"""
+xb dev 命令实现
+启动/停止开发环境
+"""
+
+import subprocess
+from pathlib import Path
+
+import click
+
+from ..utils.click_helpers import ChineseHelpCommand, HELP_CONTEXT
+
+
+def is_project_root(path: Path) -> bool:
+    return (path / "pyproject.toml").exists() and (path / "dev.sh").exists()
+
+
+def find_project_root() -> Path | None:
+    cwd = Path.cwd()
+    for path in [cwd] + list(cwd.parents):
+        if is_project_root(path):
+            return path
+    return None
+
+
+@click.command(cls=ChineseHelpCommand, context_settings=HELP_CONTEXT)
+@click.argument(
+    "action",
+    required=False,
+    default="start",
+    type=click.Choice(["start", "stop", "status"], case_sensitive=False),
+)
+def dev(action: str):
+    """启动/停止开发环境
+
+    示例:
+        xb dev
+        xb dev start
+        xb dev stop
+        xb dev status
+    """
+    project_root = find_project_root()
+    if not project_root:
+        click.echo("❌ 未找到项目根目录（缺少 pyproject.toml 或 dev.sh）")
+        raise click.Abort()
+
+    dev_script = project_root / "dev.sh"
+    subprocess.run(["bash", str(dev_script), action.lower()], cwd=project_root)

xb/commands/doctor.py

@@ -0,0 +1,91 @@
+"""
+xb doctor 命令实现
+检查本机运行 xb 生成项目所需的基础环境。
+"""
+
+from __future__ import annotations
+
+import shutil
+import socket
+import subprocess
+import sys
+from dataclasses import dataclass
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from .. import __version__
+from ..utils.click_helpers import ChineseHelpCommand, HELP_CONTEXT
+
+console = Console()
+
+
+@dataclass
+class CheckResult:
+    name: str
+    ok: bool
+    detail: str
+
+
+def _command_version(command: str, args: list[str] | None = None) -> str | None:
+    path = shutil.which(command)
+    if not path:
+        return None
+
+    cmd = [command, *(args or ['--version'])]
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=5, check=False)
+    except Exception:
+        return path
+
+    output = (result.stdout or result.stderr).strip().splitlines()
+    return output[0] if output else path
+
+
+def _port_is_free(port: int) -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.settimeout(0.3)
+        return sock.connect_ex(('127.0.0.1', port)) != 0
+
+
+def _collect_checks() -> list[CheckResult]:
+    checks = [
+        CheckResult('Python', sys.version_info >= (3, 12), sys.version.split()[0]),
+    ]
+
+    for label, command in (
+        ('uv', 'uv'),
+        ('Node.js', 'node'),
+        ('npm', 'npm'),
+        ('git', 'git'),
+    ):
+        version = _command_version(command)
+        checks.append(CheckResult(label, version is not None, version or '未找到'))
+
+    for port in (8000, 5173):
+        free = _port_is_free(port)
+        checks.append(CheckResult(f'端口 {port}', free, '可用' if free else '已被占用'))
+
+    return checks
+
+
+@click.command(cls=ChineseHelpCommand, context_settings=HELP_CONTEXT)
+def doctor() -> None:
+    """检查 xb 开发环境"""
+    console.print(f'[bold green]环境检查[/bold green] [dim]xb {__version__}[/dim]')
+
+    table = Table(show_header=True, header_style='bold cyan')
+    table.add_column('项目')
+    table.add_column('状态')
+    table.add_column('详情')
+
+    checks = _collect_checks()
+    for item in checks:
+        status = '[green]通过[/green]' if item.ok else '[red]需要处理[/red]'
+        table.add_row(item.name, status, item.detail)
+
+    console.print(table)
+
+    if not all(item.ok for item in checks):
+        console.print('[yellow]提示:[/yellow] 端口占用可先停止相关服务，或修改生成项目的 configs/global_config.yaml。')

xb/commands/init.py

@@ -0,0 +1,273 @@
+"""
+xb init 命令实现
+功能: 在当前目录初始化项目结构
+"""
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.panel import Panel
+from rich.prompt import Confirm, Prompt
+
+from .. import __version__
+from ..utils.click_helpers import ChineseHelpCommand, HELP_CONTEXT
+from ..utils.template_engine import TemplateEngine
+from ..utils.validators import validate_package_name
+from ..utils.version_check import get_latest_if_newer
+
+console = Console()
+
+
+def _prompt_upgrade_before_init() -> None:
+    """检测到新版 xb 时询问是否先升级；同意则升级后用 execvp 重跑 init 替换当前进程。
+
+    execvp 而非新起 subprocess：
+    - 升级后的 xb 入口才能加载新版依赖；当前进程已经 import 了旧模板代码
+    - 用户原始 sys.argv 直接转交，不丢任何参数（--sudoers 等）
+    """
+    latest = get_latest_if_newer(__version__)
+    if not latest:
+        return
+
+    if not Confirm.ask(
+        f"[yellow]检测到 xb {latest} 可用[/yellow]，是否先升级再创建项目？",
+        default=True,
+    ):
+        console.print("[dim]跳过升级，使用当前版本继续。[/dim]\n")
+        return
+
+    if not shutil.which("uv"):
+        console.print(
+            "[red]✗[/red] 未找到 uv 命令，无法升级。"
+            "请手动 [cyan]xb upgrade[/cyan] 或继续创建项目。"
+        )
+        if not Confirm.ask("继续用当前版本创建项目？", default=False):
+            raise click.Abort()
+        return
+
+    console.print(f"[cyan]→[/cyan] 升级到 xb-init {latest} ...")
+    result = subprocess.run(
+        ["uv", "tool", "install", "xb-init@latest", "--reinstall"],
+        check=False,
+    )
+    if result.returncode != 0:
+        console.print(f"[red]✗[/red] 升级失败 (exit {result.returncode})")
+        if not Confirm.ask("继续用当前版本创建项目？", default=False):
+            raise click.Abort()
+        return
+
+    console.print("[green]✓[/green] 升级完成，正在用新版本重新执行 init...\n")
+    xb_entry = shutil.which("xb")
+    if not xb_entry:
+        console.print(
+            "[yellow]⚠[/yellow]  升级后未找到 xb 命令，请手动重新执行：\n"
+            f"  [cyan]{' '.join(sys.argv)}[/cyan]"
+        )
+        raise click.Abort()
+    os.execvp(xb_entry, [xb_entry, *sys.argv[1:]])
+
+
+def resolve_icon_path(explicit_icon: str | None, package: str) -> Path | None:
+    """解析应用图标路径：显式 --icon 优先，其次查找约定路径。"""
+    candidates: list[Path] = []
+
+    if explicit_icon:
+        icon_path = Path(explicit_icon).expanduser()
+        if not icon_path.is_absolute():
+            icon_path = Path.cwd() / icon_path
+        if not icon_path.exists():
+            raise click.BadParameter(f"图标文件不存在: {icon_path}", param_hint="--icon")
+        return icon_path.resolve()
+
+    for name in (
+        "app-icon.png",
+        "icon.png",
+        f"{package}.png",
+        "assets/app-icon.png",
+        "assets/icon.png",
+        "resources/icon.png",
+    ):
+        candidates.append(Path.cwd() / name)
+
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate.resolve()
+
+    return None
+
+
+def init_git_repo(target_dir: Path, package: str) -> bool:
+    """在目标目录初始化 git 仓库并提交首个 commit。
+
+    成功返回 True；失败仅打印警告，不抛异常（不应阻塞项目创建）。
+    """
+    if shutil.which("git") is None:
+        console.print("[yellow]⚠[/yellow]  未检测到 git 命令，已跳过仓库初始化")
+        return False
+
+    def _run(cmd: list[str]) -> tuple[bool, str]:
+        try:
+            r = subprocess.run(
+                cmd, cwd=target_dir, capture_output=True, text=True, timeout=15
+            )
+            return r.returncode == 0, (r.stderr or r.stdout).strip()
+        except Exception as e:
+            return False, str(e)
+
+    ok, msg = _run(["git", "init", "-q"])
+    if not ok:
+        console.print(f"[yellow]⚠[/yellow]  git init 失败: {msg}")
+        return False
+
+    _run(["git", "add", "."])
+
+    ok, msg = _run(
+        ["git", "commit", "-q", "-m", f"chore: xb init 初始化 {package} 项目"]
+    )
+    if not ok:
+        console.print(
+            f"[yellow]⚠[/yellow]  git commit 失败（可能未配置 user.name/user.email）: {msg}\n"
+            f"   稍后请手动: git -C {target_dir} commit -m 'chore: xb init 初始化项目'"
+        )
+        return False
+
+    return True
+
+
+class ParamSummaryCommand(ChineseHelpCommand):
+    pass
+
+
+class XbGroup(click.Group):
+    def format_commands(self, ctx, formatter):
+        commands = []
+        for subcommand in self.list_commands(ctx):
+            cmd = self.get_command(ctx, subcommand)
+            if cmd is None:
+                continue
+            commands.append((subcommand, cmd.get_short_help_str()))
+
+        if commands:
+            formatter.width - 6 - max(len(cmd[0]) for cmd in commands)
+            rows = []
+            for subcommand, help_text in commands:
+                rows.append((subcommand, help_text))
+
+            with formatter.section("Commands"):
+                formatter.write_dl(rows)
+
+
+@click.command(cls=ParamSummaryCommand, context_settings=HELP_CONTEXT)
+@click.argument("package")
+@click.option(
+    "--sudoers",
+    is_flag=True,
+    default=False,
+    help="启用 sudo 免密配置 (需要输入密码)",
+)
+@click.option(
+    "--icon",
+    "icon",
+    type=click.Path(exists=True, dir_okay=False, path_type=str),
+    default=None,
+    help="应用图标 PNG 路径；不传时自动查找 ./app-icon.png、./icon.png、./assets/icon.png 等约定路径",
+)
+def init_command(package: str, sudoers: bool, icon: str | None):
+    """
+    初始化项目结构
+
+    在当前目录创建一个完整的 UV + FastAPI + Vue3 + Electron 项目
+
+    示例:
+        xb init demo
+        xb init myapp --sudoers
+    """
+    # 检测到 PyPI 有新版 xb 时，先询问是否升级再创建项目，避免用旧模板生成项目
+    _prompt_upgrade_before_init()
+
+    # 验证包名
+    if not validate_package_name(package):
+        console.print(
+            f"[red]✗[/red] 项目名称 '{package}' 无效! "
+            "请使用小写字母、数字和下划线 (例如: demo, my_app)",
+            style="red",
+        )
+        raise click.Abort()
+
+    # 获取当前目录
+    target_dir = Path.cwd() / package
+
+    # 检查目录是否已存在
+    if target_dir.exists():
+        console.print(f"[yellow]⚠[/yellow]  目录 {target_dir} 已存在!")
+        if not Confirm.ask("是否覆盖现有目录?", default=False):
+            console.print("[yellow]已取消操作[/yellow]")
+            raise click.Abort()
+        shutil.rmtree(target_dir)
+
+    icon_path = resolve_icon_path(icon, package)
+    if icon_path:
+        console.print(f"[green]→[/green] 使用应用图标: [cyan]{icon_path}[/cyan]")
+
+    # sudo 免密配置
+    enable_sudo = False
+    sudo_password = ""
+
+    if sudoers:
+        console.print()
+        console.print(
+            Panel.fit(
+                "[bold cyan]Sudo 免密配置[/bold cyan]\n\n"
+                "启用 sudo 免密执行特定命令。\n"
+                "密码将以明文存储在 configs/secrets.yaml 中,\n"
+                "请确保该文件权限设置为 600 (仅所有者可读写)。",
+                border_style="cyan",
+            )
+        )
+
+        sudo_password = Prompt.ask("[cyan]请输入 sudo 密码[/cyan]", password=True)
+        enable_sudo = True
+
+    # 创建项目
+    console.print()
+    console.print(f"[green]→[/green] 正在创建项目 [bold]{package}[/bold] ...")
+
+    try:
+        engine = TemplateEngine()
+        engine.render_project(
+            target_dir=target_dir,
+            package_name=package,
+            enable_sudo=enable_sudo,
+            sudo_password=sudo_password,
+            icon_path=icon_path,
+        )
+
+        git_ok = init_git_repo(target_dir, package)
+        git_line = (
+            "[green]→[/green] 已初始化 git 仓库并完成首个 commit\n"
+            if git_ok
+            else "[yellow]⚠[/yellow]  git 仓库未初始化，请稍后手动 git init\n"
+        )
+
+        console.print()
+        console.print(
+            Panel.fit(
+                f"[bold green]✓ 项目创建成功![/bold green]\n\n"
+                f"项目位置: [cyan]{target_dir}[/cyan]\n"
+                f"{git_line}\n"
+                f"[bold]下一步:[/bold]\n"
+                f"  cd {package}\n"
+                f"  bash dev.sh start    # 启动开发环境\n\n"
+                f"[dim]更多命令请查看 README.md 与 AGENTS.md[/dim]",
+                border_style="green",
+            )
+        )
+
+    except Exception as e:
+        console.print(f"[red]✗[/red] 创建项目失败: {e}", style="red")
+        raise click.Abort() from None

xb/commands/upgrade.py

@@ -0,0 +1,63 @@
+"""
+xb upgrade 命令实现
+
+封装 `uv tool install xb-init@latest --reinstall`，让用户一行命令搞定升级。
+
+为什么不用 `uv tool upgrade`：
+- uv tool 默认装包时把版本 exact-pin 到 pyproject 里 (xb-init==1.1.5)
+- `uv tool upgrade` 命令明确不破坏已有 pin，对 pin 用户它是 no-op
+- 必须用 `uv tool install <pkg>@latest --reinstall` 才能跨过 pin 取 PyPI 最新
+
+为什么不用 pip：xb 是 uv tool 装的，pip 会和 uv 管理的 venv 错乱。
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+
+import click
+
+from ..utils.click_helpers import ChineseHelpCommand, HELP_CONTEXT
+from rich.console import Console
+
+console = Console()
+
+PACKAGE_NAME = "xb-init"
+
+
+def run_upgrade() -> None:
+    """升级 xb 到 PyPI 最新版本"""
+    if not shutil.which("uv"):
+        console.print(
+            "[red]❌ 未找到 uv 命令。[/red]"
+            "请先安装 uv：[cyan]curl -LsSf https://astral.sh/uv/install.sh | sh[/cyan]"
+        )
+        sys.exit(1)
+
+    cmd = ["uv", "tool", "install", f"{PACKAGE_NAME}@latest", "--reinstall"]
+
+    console.print(f"[dim]运行: {' '.join(cmd)}[/dim]")
+    try:
+        result = subprocess.run(cmd, check=False)
+    except FileNotFoundError:
+        console.print("[red]❌ uv 命令执行失败[/red]")
+        sys.exit(1)
+
+    if result.returncode == 0:
+        console.print("[green]✅ 升级完成[/green]")
+    else:
+        console.print(f"[red]❌ 升级失败 (exit {result.returncode})[/red]")
+        sys.exit(result.returncode)
+
+
+@click.command(cls=ChineseHelpCommand, context_settings=HELP_CONTEXT)
+@click.option(
+    "--force",
+    is_flag=True,
+    help="无视 pin 强制装 PyPI 最新版（已是默认行为，保留兼容）",
+)
+def upgrade(force: bool) -> None:
+    """升级 xb 到 PyPI 最新版本"""
+    run_upgrade()