mspec-cli 4.0.0__py3-none-any.whl

mspec/__init__.py

@@ -0,0 +1,5 @@
+"""mspec - 成员规范驱动开发工作流 CLI 工具"""
+
+__version__ = "4.0.0"
+__author__ = "mspec Team"
+__email__ = "team@mspec.io"

mspec/__main__.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+"""mspec CLI 入口点"""
+
+from mspec.cli import main
+
+if __name__ == "__main__":
+    main()

mspec/cli.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""mspec CLI 入口"""
+
+import click
+from rich.console import Console
+
+from mspec.commands import doctor, init, update
+from mspec.utils.console import print_banner
+
+console = Console()
+
+
+@click.group()
+@click.version_option(version="4.0.0", prog_name="mspec")
+@click.option("--verbose", "-v", is_flag=True, help="显示详细日志")
+@click.pass_context
+def cli(ctx: click.Context, verbose: bool) -> None:
+    """mspec - 成员规范驱动开发工作流 CLI 工具
+
+    快速开始:
+        mspec init           初始化项目配置
+        mspec doctor         检查环境配置
+        mspec update         更新模板到最新版本
+
+    更多信息: https://github.com/mspec-dev/mspec
+    """
+    ctx.ensure_object(dict)
+    ctx.obj["verbose"] = verbose
+
+
+# 注册命令
+cli.add_command(init.init_cmd)
+cli.add_command(update.update_cmd)
+cli.add_command(doctor.doctor_cmd)
+
+
+def main() -> None:
+    """主入口函数"""
+    print_banner()
+    cli()
+
+
+if __name__ == "__main__":
+    main()

mspec/commands/__init__.py

@@ -0,0 +1,7 @@
+"""mspec 命令模块"""
+
+from mspec.commands.doctor import doctor_cmd
+from mspec.commands.init import init_cmd
+from mspec.commands.update import update_cmd
+
+__all__ = ["init_cmd", "update_cmd", "doctor_cmd"]

mspec/commands/doctor.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""doctor 命令实现"""
+
+import shutil
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from mspec.utils.console import print_error, print_success, print_warning
+
+console = Console()
+
+
+@click.command(name="doctor")
+def doctor_cmd() -> None:
+    """诊断环境配置
+
+    检查 mspec 运行所需的环境配置是否正确。
+
+    示例:
+        mspec doctor
+    """
+    console.print("[bold blue]🔍 mspec 环境诊断[/bold blue]\n")
+
+    checks = [
+        ("Python 版本", _check_python_version),
+        ("openspec/ 目录", _check_openspec_dir),
+        ("config.yaml", _check_config_file),
+        ("模板文件", _check_template_files),
+        ("Git 安装", _check_git),
+    ]
+
+    results = []
+    all_passed = True
+
+    for name, check_fn in checks:
+        console.print(f"  检查 {name}...", end=" ")
+        try:
+            result = check_fn()
+            if result["ok"]:
+                message = result.get("message", "")
+                if message:
+                    console.print(f"[green]✓[/green] {message}")
+                else:
+                    console.print("[green]✓[/green]")
+                results.append((name, True, result.get("message", "")))
+            else:
+                console.print(f"[red]✗[/red] {result['message']}")
+                results.append((name, False, result["message"]))
+                all_passed = False
+        except Exception as e:
+            console.print(f"[red]✗[/red] {e}")
+            results.append((name, False, str(e)))
+            all_passed = False
+
+    # 显示结果表格
+    console.print()
+    table = Table(show_header=False, box=None)
+    table.add_column("检查项")
+    table.add_column("状态")
+
+    for name, passed, _ in results:
+        status = "[green]✓ 通过[/green]" if passed else "[red]✗ 失败[/red]"
+        table.add_row(name, status)
+
+    console.print(table)
+    console.print()
+
+    if all_passed:
+        print_success("所有检查通过，环境正常！")
+    else:
+        print_warning("部分检查未通过，请参考上述提示修复")
+        sys.exit(1)
+
+
+def _check_python_version() -> dict:
+    """检查 Python 版本"""
+    if sys.version_info < (3, 8):
+        return {"ok": False, "message": "需要 Python 3.8+"}
+    return {"ok": True, "message": f"{sys.version.split()[0]}"}
+
+
+def _check_openspec_dir() -> dict:
+    """检查 openspec 目录"""
+    if not Path("openspec").exists():
+        return {
+            "ok": False,
+            "message": "未找到 openspec/ 目录，请先运行 mspec init",
+        }
+    return {"ok": True, "message": ""}
+
+
+def _check_config_file() -> dict:
+    """检查配置文件"""
+    config_path = Path("openspec/config.yaml")
+    if not config_path.exists():
+        return {"ok": False, "message": "未找到 config.yaml"}
+    return {"ok": True, "message": ""}
+
+
+def _check_template_files() -> dict:
+    """检查模板文件"""
+    templates_path = Path("openspec/templates")
+    if not templates_path.exists():
+        return {"ok": False, "message": "未找到 templates/ 目录"}
+
+    required_files = [
+        "requirement-issue-taxonomy.md",
+        "design-issue-taxonomy.md",
+        "requirement-issues.md",
+        "design-issues.md",
+    ]
+
+    missing = []
+    for file in required_files:
+        if not (templates_path / file).exists():
+            missing.append(file)
+
+    if missing:
+        return {"ok": False, "message": f"缺少文件: {', '.join(missing)}"}
+
+    return {"ok": True, "message": ""}
+
+
+def _check_git() -> dict:
+    """检查 Git 安装"""
+    if shutil.which("git") is None:
+        return {"ok": False, "message": "未找到 Git，请先安装 Git"}
+    return {"ok": True, "message": ""}

mspec/commands/init.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""init 命令实现"""
+
+from pathlib import Path
+from typing import Optional
+
+import click
+import questionary
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from mspec.core.config import ConfigManager
+from mspec.core.template import TemplateManager
+from mspec.utils.console import print_error, print_success
+
+console = Console()
+
+
+@click.command(name="init")
+@click.argument("path", required=False, default=".")
+@click.option("--template", "-t", help="使用自定义模板仓库 URL")
+@click.option("--force", "-f", is_flag=True, help="强制覆盖已有配置")
+@click.option("--dry-run", is_flag=True, help="模拟运行，不实际创建文件")
+@click.option("--yes", "-y", is_flag=True, help="跳过确认，使用默认配置")
+@click.pass_context
+def init_cmd(
+    ctx: click.Context,
+    path: str,
+    template: Optional[str],
+    force: bool,
+    dry_run: bool,
+    yes: bool,
+) -> None:
+    """初始化 mspec 项目
+
+    PATH 是项目目录路径，默认为当前目录。
+
+    示例:
+        mspec init                    # 初始化当前目录
+        mspec init ./my-project       # 初始化指定目录
+        mspec init --force            # 强制覆盖已有配置
+        mspec init --template <url>   # 使用自定义模板
+    """
+    target_path = Path(path).resolve()
+    openspec_path = target_path / "openspec"
+
+    console.print(
+        Panel.fit(
+            f"[bold blue]📦 mspec 初始化[/bold blue]\n"
+            f"目标目录: [cyan]{target_path}[/cyan]",
+            title="mspec",
+            border_style="blue",
+        )
+    )
+
+    # 检查现有配置
+    if openspec_path.exists() and not force:
+        if not yes:
+            overwrite = questionary.confirm(
+                "openspec/ 目录已存在，是否覆盖？", default=False
+            ).ask()
+            if not overwrite:
+                console.print("[yellow]已取消[/yellow]")
+                return
+
+    # 获取模板
+    template_manager = TemplateManager()
+
+    if template:
+        console.print(f"[dim]正在下载自定义模板: {template}[/dim]")
+        try:
+            files = template_manager.download_from_url(template)
+        except Exception as e:
+            print_error(f"下载模板失败: {e}")
+            return
+    else:
+        console.print("[dim]使用内置模板[/dim]")
+        files = template_manager.get_builtin_templates()
+
+    # 模拟运行模式
+    if dry_run:
+        _show_dry_run(files, target_path)
+        return
+
+    # 确认安装
+    if not yes:
+        _show_files_table(files, target_path)
+        confirm = questionary.confirm("确认初始化?", default=True).ask()
+        if not confirm:
+            return
+
+    # 创建目录和文件
+    console.print("\n[dim]正在创建文件...[/dim]")
+    try:
+        _create_files(files, openspec_path)
+        print_success("文件创建完成")
+    except Exception as e:
+        print_error(f"创建文件失败: {e}")
+        return
+
+    # 验证安装
+    console.print("[dim]正在验证配置...[/dim]")
+    config_manager = ConfigManager(openspec_path)
+    validation = config_manager.validate()
+
+    if validation.valid:
+        print_success("验证通过")
+        _print_success_message()
+    else:
+        print_error("验证失败:")
+        for error in validation.errors:
+            console.print(f"  [red]• {error}[/red]")
+
+
+def _show_dry_run(files: dict, target_path: Path) -> None:
+    """显示模拟运行信息"""
+    console.print("\n[cyan]📋 模拟运行 - 将创建以下文件：[/cyan]")
+    for file_path in files.keys():
+        full_path = target_path / "openspec" / file_path
+        console.print(f"  [green]✓[/green] {full_path}")
+
+
+def _show_files_table(files: dict, target_path: Path) -> None:
+    """显示文件表格"""
+    table = Table(title="将创建以下文件")
+    table.add_column("文件", style="cyan")
+    table.add_column("大小", style="dim")
+
+    for file_path, content in files.items():
+        size = len(content.encode("utf-8"))
+        size_str = f"{size} B" if size < 1024 else f"{size / 1024:.1f} KB"
+        table.add_row(str(file_path), size_str)
+
+    console.print()
+    console.print(table)
+
+
+def _create_files(files: dict, openspec_path: Path) -> None:
+    """创建文件"""
+    openspec_path.mkdir(parents=True, exist_ok=True)
+    (openspec_path / "templates").mkdir(exist_ok=True)
+
+    for file_path, content in files.items():
+        full_path = openspec_path / file_path
+        full_path.parent.mkdir(parents=True, exist_ok=True)
+        full_path.write_text(content, encoding="utf-8")
+        console.print(f"  [green]✓[/green] {file_path}")
+
+
+def _print_success_message() -> None:
+    """打印成功消息"""
+    console.print("\n[bold green]✅ 初始化完成![/bold green]\n")
+    console.print("接下来你可以：")
+    console.print("  • 使用 [cyan]/opsx:propose[/cyan] 创建新变更")
+    console.print("  • 使用 [cyan]mspec doctor[/cyan] 检查环境")
+    console.print("  • 查看 [cyan]https://docs.mspec.io[/cyan] 获取完整文档")

mspec/commands/update.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""update 命令实现"""
+
+import shutil
+from datetime import datetime
+from pathlib import Path
+
+import click
+import semver
+from rich.console import Console
+
+from mspec.core.config import ConfigManager
+from mspec.core.template import TemplateManager
+from mspec.utils.console import print_error, print_success, print_warning
+
+console = Console()
+
+
+@click.command(name="update")
+@click.option("--check", is_flag=True, help="仅检查更新，不执行更新")
+def update_cmd(check: bool) -> None:
+    """更新模板到最新版本
+
+    自动检测并更新到最新版本的模板，同时保留用户的自定义配置。
+
+    示例:
+        mspec update          # 更新到最新版本
+        mspec update --check  # 仅检查是否有更新
+    """
+    console.print("[bold blue]🔄 检查更新...[/bold blue]\n")
+
+    # 检查当前版本
+    openspec_path = Path("openspec")
+    if not openspec_path.exists():
+        print_error("未找到 openspec/ 目录，请先运行 mspec init")
+        return
+
+    config_manager = ConfigManager(openspec_path)
+    current_version = config_manager.get_version()
+
+    console.print(f"当前版本: [cyan]{current_version}[/cyan]")
+
+    # 获取远程最新版本
+    template_manager = TemplateManager()
+    try:
+        latest_version = template_manager.get_latest_version()
+    except Exception as e:
+        print_error(f"获取最新版本失败: {e}")
+        return
+
+    console.print(f"最新版本: [cyan]{latest_version}[/cyan]")
+
+    # 比较版本
+    try:
+        if semver.compare(current_version, latest_version) >= 0:
+            print_success(f"已是最新版本 ({current_version})")
+            return
+    except ValueError:
+        # 版本号格式错误，继续尝试更新
+        pass
+
+    if check:
+        print_warning(f"发现新版本: {current_version} → {latest_version}")
+        return
+
+    # 执行更新
+    console.print(f"\n[yellow]正在更新到 {latest_version}...[/yellow]\n")
+
+    try:
+        # 备份旧配置
+        backup_path = _backup_config()
+        console.print(f"[dim]旧配置已备份到: {backup_path}[/dim]")
+
+        # 下载新模板
+        new_templates = template_manager.download_latest()
+
+        # 合并配置
+        merged_config = config_manager.merge_with_new(new_templates)
+
+        # 写入新配置
+        config_manager.write(merged_config)
+
+        print_success("更新完成!")
+        console.print(f"\n[dim]旧配置备份: {backup_path}[/dim]")
+
+    except Exception as e:
+        print_error(f"更新失败: {e}")
+        console.print("[yellow]建议从备份恢复[/yellow]")
+
+
+def _backup_config() -> Path:
+    """备份当前配置"""
+    openspec_path = Path("openspec")
+    backup_dir = Path.home() / ".mspec" / "backups"
+    backup_dir.mkdir(parents=True, exist_ok=True)
+
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    backup_path = backup_dir / f"openspec_backup_{timestamp}"
+
+    if backup_path.exists():
+        shutil.rmtree(backup_path)
+
+    shutil.copytree(openspec_path, backup_path)
+    return backup_path

mspec/core/__init__.py

@@ -0,0 +1,6 @@
+"""mspec 核心模块"""
+
+from mspec.core.config import ConfigManager
+from mspec.core.template import TemplateManager
+
+__all__ = ["ConfigManager", "TemplateManager"]

mspec/core/config.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""配置管理模块"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List
+
+import yaml
+
+
+@dataclass
+class ValidationResult:
+    """验证结果"""
+    valid: bool
+    errors: List[str] = field(default_factory=list)
+
+
+class ConfigManager:
+    """配置管理器"""
+
+    def __init__(self, openspec_path: Path):
+        self.openspec_path = Path(openspec_path)
+        self.config_path = self.openspec_path / "config.yaml"
+
+    def get_version(self) -> str:
+        """获取当前配置版本"""
+        if not self.config_path.exists():
+            return "0.0.0"
+
+        try:
+            content = yaml.safe_load(self.config_path.read_text(encoding="utf-8"))
+            if content and isinstance(content, dict):
+                return content.get("version", "4.0.0")
+            return "4.0.0"
+        except Exception:
+            return "4.0.0"
+
+    def validate(self) -> ValidationResult:
+        """验证配置是否完整
+
+        Returns:
+            验证结果
+        """
+        errors = []
+
+        # 检查 config.yaml
+        if not self.config_path.exists():
+            errors.append("未找到 config.yaml")
+        else:
+            try:
+                config = yaml.safe_load(self.config_path.read_text(encoding="utf-8"))
+                if not config or not isinstance(config, dict):
+                    errors.append("config.yaml 格式错误")
+                elif not config.get("schema"):
+                    errors.append("config.yaml 缺少 schema 字段")
+            except yaml.YAMLError as e:
+                errors.append(f"config.yaml 格式错误: {e}")
+
+        # 检查模板文件
+        templates_path = self.openspec_path / "templates"
+        required_templates = [
+            "requirement-issue-taxonomy.md",
+            "design-issue-taxonomy.md",
+            "requirement-issues.md",
+            "design-issues.md",
+        ]
+
+        for template in required_templates:
+            if not (templates_path / template).exists():
+                errors.append(f"缺少模板文件: {template}")
+
+        return ValidationResult(valid=len(errors) == 0, errors=errors)
+
+    def merge_with_new(self, new_templates: Dict[str, str]) -> Dict[str, Any]:
+        """合并现有配置与新模板
+
+        Args:
+            new_templates: 新模板内容
+
+        Returns:
+            合并后的配置
+        """
+        # 读取现有配置
+        current_config = {}
+        if self.config_path.exists():
+            try:
+                current_config = yaml.safe_load(self.config_path.read_text(encoding="utf-8")) or {}
+            except Exception:
+                current_config = {}
+
+        # 解析新配置
+        new_config = {}
+        if "config.yaml" in new_templates:
+            try:
+                new_config = yaml.safe_load(new_templates["config.yaml"]) or {}
+            except Exception:
+                new_config = {}
+
+        # 合并策略：
+        # 1. 系统字段使用新版本
+        # 2. 用户自定义字段保留
+        merged = {
+            "schema": new_config.get("schema", "spec-driven"),
+            "version": new_config.get("version", "4.0.0"),
+            "language": current_config.get("language", new_config.get("language", "zh")),
+            "context": self._merge_context(
+                current_config.get("context", ""),
+                new_config.get("context", "")
+            ),
+            "rules": self._merge_rules(
+                current_config.get("rules", {}),
+                new_config.get("rules", {})
+            ),
+        }
+
+        return merged
+
+    def _merge_context(self, current: str, new: str) -> str:
+        """合并 context 字段"""
+        if current and new and new not in current:
+            return f"{current}\n\n# 以下为新版本添加的内容\n{new}"
+        return new or current
+
+    def _merge_rules(self, current: Dict, new: Dict) -> Dict:
+        """合并 rules 字段"""
+        # 使用新版本的规则为主
+        merged = dict(new)
+
+        # 但保留用户的自定义规则
+        for key, value in current.items():
+            if key not in merged:
+                merged[key] = value
+
+        return merged
+
+    def write(self, config: Dict[str, Any]) -> None:
+        """写入配置"""
+        self.config_path.write_text(
+            yaml.dump(config, allow_unicode=True, sort_keys=False),
+            encoding="utf-8"
+        )