mspec-cli 4.0.2__tar.gz → 4.0.5__tar.gz

{mspec_cli-4.0.2/src/mspec_cli.egg-info → mspec_cli-4.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mspec-cli
-Version: 4.0.2
+Version: 4.0.5
 Summary: mspec-cli - 成员规范驱动开发工作流 CLI 工具
 Author-email: shirayner <team@mspec.io>
 License: MIT
@@ -57,8 +57,29 @@ Dynamic: license-file
 
 ## 文档
 
-- [EVOLUTION.md](docs/EVOLUTION.md) - mspec 演进历程 (v1 → v4)
-- [SPEC-ARCHIVE.md](docs/SPEC-ARCHIVE.md) - 完整技术规范参考
+📚 **[完整文档 →](docs/)**
+
+### 新手入门
+- [📖 安装指南](docs/getting-started/installation.md) - 系统要求与安装步骤
+- [⚡ 5分钟快速开始](docs/getting-started/quickstart.md) - 体验完整流程
+- [🎯 第一个完整变更](docs/getting-started/first-change.md) - 从零到交付的详细教程
+
+### 完整指南
+- [💡 核心概念](docs/guide/concepts.md) - Change、Capability、问题分类学
+- [🔧 CLI 命令详解](docs/guide/cli-commands.md) - init、update、doctor
+- [📋 工作流详解](docs/guide/) - 探索 → 澄清 → 提案 → 设计 → 实施 → 归档
+
+### 实战教程
+- [🛠️ Todo 应用开发](docs/tutorial/todo-app/) - 从零开发完整项目
+
+### 参考手册
+- [📖 CLI 命令速查](docs/reference/cli-reference.md)
+- [⚙️ 配置参考](docs/reference/config-reference.md)
+- [🗂️ 问题分类学参考](docs/reference/taxonomy-reference.md)
+
+### 其他
+- [❓ 常见问题 (FAQ)](docs/faq.md)
+- [🐛 故障排除](docs/troubleshooting.md)
 
 ## 快速开始
 

{mspec_cli-4.0.2 → mspec_cli-4.0.5}/README.md

@@ -18,8 +18,29 @@
 
 ## 文档
 
-- [EVOLUTION.md](docs/EVOLUTION.md) - mspec 演进历程 (v1 → v4)
-- [SPEC-ARCHIVE.md](docs/SPEC-ARCHIVE.md) - 完整技术规范参考
+📚 **[完整文档 →](docs/)**
+
+### 新手入门
+- [📖 安装指南](docs/getting-started/installation.md) - 系统要求与安装步骤
+- [⚡ 5分钟快速开始](docs/getting-started/quickstart.md) - 体验完整流程
+- [🎯 第一个完整变更](docs/getting-started/first-change.md) - 从零到交付的详细教程
+
+### 完整指南
+- [💡 核心概念](docs/guide/concepts.md) - Change、Capability、问题分类学
+- [🔧 CLI 命令详解](docs/guide/cli-commands.md) - init、update、doctor
+- [📋 工作流详解](docs/guide/) - 探索 → 澄清 → 提案 → 设计 → 实施 → 归档
+
+### 实战教程
+- [🛠️ Todo 应用开发](docs/tutorial/todo-app/) - 从零开发完整项目
+
+### 参考手册
+- [📖 CLI 命令速查](docs/reference/cli-reference.md)
+- [⚙️ 配置参考](docs/reference/config-reference.md)
+- [🗂️ 问题分类学参考](docs/reference/taxonomy-reference.md)
+
+### 其他
+- [❓ 常见问题 (FAQ)](docs/faq.md)
+- [🐛 故障排除](docs/troubleshooting.md)
 
 ## 快速开始
 

{mspec_cli-4.0.2 → mspec_cli-4.0.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mspec-cli"
-version = "4.0.2"
+version = "4.0.5"
 description = "mspec-cli - 成员规范驱动开发工作流 CLI 工具"
 readme = "README.md"
 license = {text = "MIT"}

{mspec_cli-4.0.2 → mspec_cli-4.0.5}/src/mspec/commands/doctor.py

@@ -9,6 +9,7 @@ import click
 from rich.console import Console
 from rich.table import Table
 
+from mspec.core.openspec_manager import OpenspecManager, OpenspecStatus
 from mspec.utils.console import print_error, print_success, print_warning
 
 console = Console()
@@ -27,6 +28,7 @@ def doctor_cmd() -> None:
 
     checks = [
         ("Python 版本", _check_python_version),
+        ("openspec CLI", _check_openspec_cli),
         ("openspec/ 目录", _check_openspec_dir),
         ("config.yaml", _check_config_file),
         ("模板文件", _check_template_files),
@@ -83,6 +85,27 @@ def _check_python_version() -> dict:
     return {"ok": True, "message": f"{sys.version.split()[0]}"}
 
 
+def _check_openspec_cli() -> dict:
+    """检查 openspec CLI 是否安装"""
+    manager = OpenspecManager()
+    status = manager.check()
+
+    if status == OpenspecStatus.INSTALLED:
+        version = manager.get_version()
+        version_str = f" ({version})" if version else ""
+        return {"ok": True, "message": f"已安装{version_str}"}
+    elif status == OpenspecStatus.NPX_AVAILABLE:
+        return {
+            "ok": True,
+            "message": "未全局安装，但可通过 npx 运行",
+        }
+    else:
+        return {
+            "ok": False,
+            "message": "未安装。运行 `npm install -g @fission-ai/openspec` 安装",
+        }
+
+
 def _check_openspec_dir() -> dict:
     """检查 openspec 目录"""
     if not Path("openspec").exists():

{mspec_cli-4.0.2 → mspec_cli-4.0.5}/src/mspec/commands/init.py

@@ -12,6 +12,7 @@ from rich.panel import Panel
 from rich.table import Table
 
 from mspec.core.config import ConfigManager
+from mspec.core.openspec_manager import OpenspecManager, OpenspecStatus
 from mspec.core.template import TemplateManager
 from mspec.utils.console import print_error, print_success
 
@@ -117,27 +118,67 @@ def init_cmd(
             console.print(f"  [red]• {error}[/red]")
 
 
-def _run_openspec_init(target_path: Path) -> None:
-    """调用 openspec init 初始化 OpenSpec 目录结构"""
-    console.print("\n[dim]正在调用 openspec init...[/dim]")
+def _run_openspec_init(target_path: Path) -> bool:
+    """调用 openspec init 初始化 OpenSpec 目录结构
+
+    支持自动检测 openspec，如未安装则尝试使用 npx 或自动安装
+
+    Args:
+        target_path: 目标目录路径
+
+    Returns:
+        bool: 是否成功调用 openspec init
+    """
+    manager = OpenspecManager()
+
+    # 1. 检查当前状态
+    status = manager.check()
+
+    if status == OpenspecStatus.INSTALLED:
+        console.print("[dim]检测到 openspec 已安装[/dim]")
+    elif status == OpenspecStatus.NPX_AVAILABLE:
+        console.print("[dim]openspec 未全局安装，将使用 npx 运行[/dim]")
+    else:
+        # 检查 npm 是否安装
+        import shutil
+
+        if not shutil.which("npm"):
+            manager.print_npm_not_found_guide()
+            # 询问是否继续（不使用 openspec）
+            continue_anyway = questionary.confirm(
+                "是否继续初始化（跳过 openspec）?", default=True
+            ).ask()
+            return continue_anyway
+
+        console.print("[yellow]openspec 未安装，正在尝试自动安装...[/yellow]")
+        if manager.install():
+            # 重新检测
+            status = manager.check()
+        else:
+            # 安装失败，打印指引
+            manager.print_install_guide()
+            # 询问是否继续（不使用 openspec）
+            continue_anyway = questionary.confirm(
+                "是否继续初始化（跳过 openspec）?", default=True
+            ).ask()
+            return continue_anyway
+
+    # 2. 执行 openspec init
+    console.print("[dim]正在调用 openspec init...[/dim]")
     try:
-        result = subprocess.run(
-            ["openspec", "init"],
-            cwd=str(target_path),
-            capture_output=True,
-            text=True,
-        )
+        result = manager.run(["init"], cwd=target_path)
         if result.returncode == 0:
-            console.print("[dim]openspec init 完成[/dim]")
+            console.print("[green]✓ openspec init 完成[/green]")
+            return True
         else:
-            console.print(
-                f"[yellow]⚠ openspec init 返回非零退出码，继续执行...[/yellow]"
-            )
-    except FileNotFoundError:
-        console.print(
-            "[yellow]⚠ openspec 未安装，跳过 openspec init。"
-            "请手动执行 `openspec init` 以完成完整初始化。[/yellow]"
-        )
+            if result.stderr:
+                console.print(f"[yellow]⚠ openspec init 返回警告: {result.stderr}[/yellow]")
+            else:
+                console.print("[yellow]⚠ openspec init 返回非零退出码，继续执行...[/yellow]")
+            return True  # 仍视为成功，继续执行
+    except Exception as e:
+        console.print(f"[yellow]⚠ openspec init 执行异常: {e}[/yellow]")
+        return True  # 仍视为成功，继续执行
 
 
 def _show_dry_run(files: dict, target_path: Path) -> None:

mspec_cli-4.0.5/src/mspec/core/openspec_manager.py

@@ -0,0 +1,232 @@
+#!/usr/bin/env python3
+"""openspec 管理模块
+
+负责检测、安装和调用 openspec
+"""
+
+import platform
+import shutil
+import subprocess
+from enum import Enum
+from pathlib import Path
+from typing import List, Optional
+
+from rich.console import Console
+
+console = Console()
+
+
+class OpenspecStatus(Enum):
+    """openspec 状态"""
+
+    INSTALLED = "installed"  # 已全局安装
+    NPX_AVAILABLE = "npx"  # 可通过 npx 运行
+    NOT_FOUND = "not_found"  # 未安装且无法自动安装
+
+
+class OpenspecManager:
+    """openspec 管理器
+
+    负责检测、安装和调用 openspec
+    """
+
+    PACKAGE_NAME = "@fission-ai/openspec"
+
+    def __init__(self):
+        self._status: Optional[OpenspecStatus] = None
+
+    def check(self) -> OpenspecStatus:
+        """检查 openspec 可用状态
+
+        Returns:
+            OpenspecStatus: 当前状态
+        """
+        if self._status is not None:
+            return self._status
+
+        # 1. 检查全局安装
+        # Windows 上优先检查 openspec.cmd，因为 npm 会安装 openspec.cmd
+        if self._is_windows():
+            if shutil.which("openspec.cmd") or shutil.which("openspec"):
+                self._status = OpenspecStatus.INSTALLED
+                return self._status
+        else:
+            if shutil.which("openspec"):
+                self._status = OpenspecStatus.INSTALLED
+                return self._status
+
+        # 2. 检查 npx 是否可用
+        if shutil.which("npx"):
+            self._status = OpenspecStatus.NPX_AVAILABLE
+            return self._status
+
+        self._status = OpenspecStatus.NOT_FOUND
+        return self._status
+
+    def _is_windows(self) -> bool:
+        """检查是否为 Windows 系统"""
+        return platform.system() == "Windows"
+
+    def is_available(self) -> bool:
+        """检查是否可用（已安装或可通过 npx 运行）"""
+        return self.check() != OpenspecStatus.NOT_FOUND
+
+    def _get_openspec_cmd(self) -> List[str]:
+        """获取正确的 openspec 命令
+
+        在 Windows 上，npm 会安装三个文件：
+        - openspec (无扩展名的 shell script，Unix 兼容)
+        - openspec.cmd (Windows batch 文件)
+        - openspec.ps1 (PowerShell 脚本)
+
+        Windows 无法直接执行无扩展名的 shell script，
+        所以需要优先使用 .cmd 版本。
+
+        Returns:
+            List[str]: 命令列表，如 ["openspec"] 或 ["openspec.cmd"]
+        """
+        # Windows 优先使用 openspec.cmd
+        if self._is_windows():
+            # 先尝试直接找 openspec.cmd
+            cmd_path = shutil.which("openspec.cmd")
+            if cmd_path:
+                return [cmd_path]
+
+            # 如果没找到，但找到了 openspec（无扩展名），
+            # 尝试在同一目录下找 openspec.cmd
+            openspec_path = shutil.which("openspec")
+            if openspec_path:
+                # 构建 openspec.cmd 的完整路径
+                base_path = openspec_path.replace("/openspec", "/openspec.cmd")
+                base_path = base_path.replace("\\openspec", "\\openspec.cmd")
+                if Path(base_path).exists():
+                    return [base_path]
+
+        # 非 Windows 或找不到 .cmd，使用默认命令
+        openspec_path = shutil.which("openspec")
+        if openspec_path:
+            return [openspec_path]
+
+        return ["openspec"]
+
+    def run(self, args: list, cwd: Optional[Path] = None) -> subprocess.CompletedProcess:
+        """运行 openspec 命令
+
+        Args:
+            args: 命令参数
+            cwd: 工作目录
+
+        Returns:
+            subprocess.CompletedProcess: 执行结果
+
+        Raises:
+            RuntimeError: 当 openspec 不可用时
+        """
+        status = self.check()
+
+        if status == OpenspecStatus.INSTALLED:
+            cmd = self._get_openspec_cmd() + args
+        elif status == OpenspecStatus.NPX_AVAILABLE:
+            cmd = ["npx", self.PACKAGE_NAME] + args
+        else:
+            raise RuntimeError("openspec 不可用")
+
+        return subprocess.run(
+            cmd,
+            cwd=str(cwd) if cwd else None,
+            capture_output=True,
+            text=True,
+        )
+
+    def install(self, global_install: bool = True) -> bool:
+        """安装 openspec
+
+        Args:
+            global_install: 是否全局安装
+
+        Returns:
+            bool: 是否安装成功
+        """
+        if not shutil.which("npm"):
+            console.print("[red]✗ npm 未安装，无法自动安装 openspec[/red]")
+            return False
+
+        try:
+            cmd = ["npm", "install"]
+            if global_install:
+                cmd.append("-g")
+            cmd.append(self.PACKAGE_NAME)
+
+            console.print(f"[dim]正在执行: {' '.join(cmd)}[/dim]")
+
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=180,  # 3分钟超时
+            )
+
+            if result.returncode == 0:
+                # 清除缓存，重新检测
+                self._status = None
+                console.print("[green]✓ openspec 安装成功[/green]")
+                return True
+            else:
+                # 检查是否是权限问题
+                if "EACCES" in result.stderr or "permission" in result.stderr.lower():
+                    console.print("[yellow]⚠ 权限不足，无法全局安装[/yellow]")
+                else:
+                    console.print(f"[red]✗ 安装失败: {result.stderr}[/red]")
+                return False
+
+        except subprocess.TimeoutExpired:
+            console.print("[red]✗ 安装超时[/red]")
+            return False
+        except Exception as e:
+            console.print(f"[red]✗ 安装出错: {e}[/red]")
+            return False
+
+    def print_install_guide(self):
+        """打印安装指引"""
+        console.print("\n[bold yellow]⚠ openspec 未安装[/bold yellow]")
+        console.print("\n请执行以下命令安装:")
+        console.print(f"  [cyan]npm install -g {self.PACKAGE_NAME}[/cyan]")
+        console.print("\n[dim]如果权限不足，请尝试:[/dim]")
+        console.print(f"  [cyan]sudo npm install -g {self.PACKAGE_NAME}[/cyan]")
+        console.print("\n或使用 npx（无需安装）:")
+        console.print(f"  [cyan]npx {self.PACKAGE_NAME} init[/cyan]")
+
+    def print_npm_not_found_guide(self):
+        """打印 npm 未安装的指引"""
+        console.print("\n[bold red]✗ npm 未安装[/bold red]")
+        console.print("\n[yellow]openspec 需要 Node.js 环境，请安装 Node.js:[/yellow]")
+        console.print("  https://nodejs.org/")
+        console.print("\n[dim]安装后请重新运行 mspec init[/dim]")
+
+    def print_permission_guide(self):
+        """打印权限问题的解决指引"""
+        console.print("\n[yellow]⚠ npm 全局安装权限不足[/yellow]")
+        console.print("\n解决方案 1 - 使用 npx（推荐，无需安装）:")
+        console.print(f"  [cyan]npx {self.PACKAGE_NAME} init[/cyan]")
+        console.print("\n解决方案 2 - 修改 npm 权限:")
+        console.print("  https://docs.npmjs.com/resolving-eacces-permissions-errors")
+        console.print("\n解决方案 3 - 使用 sudo:")
+        console.print(f"  [cyan]sudo npm install -g {self.PACKAGE_NAME}[/cyan]")
+
+    def get_version(self) -> Optional[str]:
+        """获取 openspec 版本
+
+        Returns:
+            Optional[str]: 版本号，如果未安装则返回 None
+        """
+        if not self.is_available():
+            return None
+
+        try:
+            result = self.run(["--version"])
+            if result.returncode == 0:
+                return result.stdout.strip()
+        except Exception:
+            pass
+
+        return None

{mspec_cli-4.0.2 → mspec_cli-4.0.5/src/mspec_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mspec-cli
-Version: 4.0.2
+Version: 4.0.5
 Summary: mspec-cli - 成员规范驱动开发工作流 CLI 工具
 Author-email: shirayner <team@mspec.io>
 License: MIT
@@ -57,8 +57,29 @@ Dynamic: license-file
 
 ## 文档
 
-- [EVOLUTION.md](docs/EVOLUTION.md) - mspec 演进历程 (v1 → v4)
-- [SPEC-ARCHIVE.md](docs/SPEC-ARCHIVE.md) - 完整技术规范参考
+📚 **[完整文档 →](docs/)**
+
+### 新手入门
+- [📖 安装指南](docs/getting-started/installation.md) - 系统要求与安装步骤
+- [⚡ 5分钟快速开始](docs/getting-started/quickstart.md) - 体验完整流程
+- [🎯 第一个完整变更](docs/getting-started/first-change.md) - 从零到交付的详细教程
+
+### 完整指南
+- [💡 核心概念](docs/guide/concepts.md) - Change、Capability、问题分类学
+- [🔧 CLI 命令详解](docs/guide/cli-commands.md) - init、update、doctor
+- [📋 工作流详解](docs/guide/) - 探索 → 澄清 → 提案 → 设计 → 实施 → 归档
+
+### 实战教程
+- [🛠️ Todo 应用开发](docs/tutorial/todo-app/) - 从零开发完整项目
+
+### 参考手册
+- [📖 CLI 命令速查](docs/reference/cli-reference.md)
+- [⚙️ 配置参考](docs/reference/config-reference.md)
+- [🗂️ 问题分类学参考](docs/reference/taxonomy-reference.md)
+
+### 其他
+- [❓ 常见问题 (FAQ)](docs/faq.md)
+- [🐛 故障排除](docs/troubleshooting.md)
 
 ## 快速开始
 

{mspec_cli-4.0.2 → mspec_cli-4.0.5}/src/mspec_cli.egg-info/SOURCES.txt

@@ -11,6 +11,7 @@ src/mspec/commands/init.py
 src/mspec/commands/update.py
 src/mspec/core/__init__.py
 src/mspec/core/config.py
+src/mspec/core/openspec_manager.py
 src/mspec/core/template.py
 src/mspec/templates/config.yaml
 src/mspec/templates/design-issue-taxonomy.md