precis-cli 0.1.3__py3-none-any.whl

app/cli/shell/parser.py

@@ -0,0 +1,266 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# backend/app/cli/shell/parser.py
+"""
+@fileoverview CLI Shell 命令解析与注册模块
+
+功能概述:
+- 管理所有可用命令的注册和查找
+- 解析用户输入并分发到对应命令执行
+- 支持引号包围的参数分割
+
+架构设计:
+- CommandRegistry 维护命令名称与别名的映射
+- CommandParser 分割参数并查找对应命令
+- CommandExecutor 协调解析与上下文执行
+"""
+
+from collections.abc import Callable
+
+from app.cli.shell.commands.base import Command, CommandResult, ProjectContext
+from app.cli.shell.exceptions import CommandNotFoundError
+
+
+class CommandRegistry:
+    """命令注册表。
+
+    管理所有可用命令的注册和查找。
+    """
+
+    def __init__(self) -> None:
+        self._commands: dict[str, Command] = {}
+        self._aliases: dict[str, str] = {}
+
+    def register(self, command: Command) -> None:
+        """注册命令。
+
+        Args:
+            command: 命令实例
+        """
+        self._commands[command.name] = command
+        for alias in command.aliases:
+            self._aliases[alias] = command.name
+
+    def unregister(self, name: str) -> None:
+        """注销命令。
+
+        Args:
+            name: 命令名称
+        """
+        if name in self._commands:
+            command = self._commands[name]
+            for alias in command.aliases:
+                self._aliases.pop(alias, None)
+            self._commands.pop(name)
+
+    def get(self, name: str) -> Command | None:
+        """获取命令。
+
+        Args:
+            name: 命令名称或别名
+
+        Returns:
+            命令实例，如果不存在则返回 None
+        """
+        if name in self._commands:
+            return self._commands[name]
+        if name in self._aliases:
+            return self._commands[self._aliases[name]]
+        return None
+
+    def list_commands(self) -> list[str]:
+        """列出所有注册的命令名称。"""
+        return list(self._commands.keys())
+
+    def get_all_commands(self) -> list[Command]:
+        """获取所有已注册的命令。"""
+        return list(self._commands.values())
+
+
+class CommandParser:
+    """命令解析器。
+
+    解析用户输入并分发到对应命令执行。
+    """
+
+    def __init__(self, registry: CommandRegistry):
+        self.registry = registry
+
+    def parse(self, input_line: str) -> tuple[Command | None, list[str]]:
+        """解析输入行。
+
+        Args:
+            input_line: 用户输入的行
+
+        Returns:
+            (命令实例, 参数列表) 元组
+        """
+        input_line = input_line.strip()
+        if not input_line:
+            return None, []
+
+        parts = self._split_args(input_line)
+        if not parts:
+            return None, []
+
+        command_name = parts[0]
+        args = parts[1:]
+
+        command = self.registry.get(command_name)
+        if command is None:
+            raise CommandNotFoundError(command_name)
+
+        return command, args
+
+    def _split_args(self, line: str) -> list[str]:
+        """分割命令行参数（4.6 重写：引号状态机）。
+
+        - 全角空格（U+3000）先归一为半角再分词
+        - 撇号（'）与双引号（"）同作引号配对处理，支持反斜杠转义引号
+        - 输入结束引号未闭合时显式报错（原实现静默合并剩余输入，掩盖真实根因）
+
+        Args:
+            line: 输入行
+
+        Returns:
+            参数列表
+
+        Raises:
+            ValueError: 引号未闭合
+        """
+        # 全角空格归一（中文输入法常见，归一后按普通分隔符处理）
+        normalized = line.replace("　", " ")
+
+        tokens: list[str] = []
+        current: list[str] = []
+        in_quote = False
+        quote_char: str | None = None
+
+        i = 0
+        while i < len(normalized):
+            char = normalized[i]
+
+            if in_quote:
+                if char == "\\" and i + 1 < len(normalized) and normalized[i + 1] in ('"', "'"):
+                    # 转义引号：保留引号本身
+                    current.append(normalized[i + 1])
+                    i += 2
+                    continue
+                if char == quote_char:
+                    in_quote = False
+                    quote_char = None
+                else:
+                    current.append(char)
+            else:
+                if char in ('"', "'"):
+                    in_quote = True
+                    quote_char = char
+                elif char == " ":
+                    if current:
+                        tokens.append("".join(current))
+                        current = []
+                else:
+                    current.append(char)
+            i += 1
+
+        if in_quote and quote_char:
+            raise ValueError(f"引号未闭合: 缺少配对的 {quote_char}")
+
+        if current:
+            tokens.append("".join(current))
+
+        return tokens
+
+
+class CommandExecutor:
+    """命令执行器。
+
+    负责执行解析后的命令。
+    """
+
+    def __init__(self, parser: CommandParser, context: ProjectContext):
+        self.parser = parser
+        self.context = context
+
+    def execute(self, input_line: str) -> CommandResult:
+        """执行命令。
+
+        Args:
+            input_line: 用户输入的行
+
+        Returns:
+            命令执行结果
+        """
+        try:
+            command, args = self.parser.parse(input_line)
+            if command is None:
+                return CommandResult.error("请输入命令")
+
+            return command.execute(args, self.context)
+        except CommandNotFoundError as e:
+            # 命令不存在属参数错误，单发模式下退出码 2（工具自身错误）
+            return CommandResult.error(str(e), exit_code=2)
+        except Exception as e:
+            # 命令异常崩溃属工具自身错误，单发模式下退出码 2（区别于校验发现违规的 1）
+            return CommandResult.error(f"命令执行失败: {e}", exit_code=2)
+
+    def execute_with_args(self, args: list[str]) -> CommandResult:
+        """使用预分割参数列表执行命令。
+
+        跳过 join/split 循环，保留参数中的空格（如文件路径）。
+
+        Args:
+            args: 预分割的参数列表，第一个元素为命令名
+
+        Returns:
+            命令执行结果
+        """
+        try:
+            if not args:
+                return CommandResult.error("请输入命令")
+
+            command = self.parser.registry.get(args[0])
+            if command is None:
+                raise CommandNotFoundError(args[0])
+
+            return command.execute(args[1:], self.context)
+        except CommandNotFoundError as e:
+            # 命令不存在属参数错误，单发模式下退出码 2（工具自身错误）
+            return CommandResult.error(str(e), exit_code=2)
+        except Exception as e:
+            # 命令异常崩溃属工具自身错误，单发模式下退出码 2（区别于校验发现违规的 1）
+            return CommandResult.error(f"命令执行失败: {e}", exit_code=2)
+
+
+def command(name: str, aliases: list[str] | None = None) -> Callable:
+    """命令装饰器。
+
+    用于注册命令类的装饰器。
+
+    Args:
+        name: 命令名称
+        aliases: 命令别名
+
+    Returns:
+        装饰器函数
+    """
+
+    def decorator(cls: type[Command]) -> type[Command]:
+        cls.name = name
+        cls.aliases = aliases or []
+        return cls
+
+    return decorator

app/cli/start.py

@@ -0,0 +1,180 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+Precis Web Mode - Start Server
+
+Usage:
+    precis-start [--work-dir <path>] [--port <port>] [--no-browser]
+
+Starts the FastAPI backend server and opens the browser for Web mode.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import webbrowser
+from pathlib import Path
+
+from app.shared.core.config.server import (
+    DEFAULT_BACKEND_HOST,
+    acquire_port,
+    clear_port_file,
+    register_port_file_cleanup,
+    resolve_port,
+    write_port_file,
+)
+
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="precis-start",
+        description="Start Precis in Web mode",
+    )
+    parser.add_argument(
+        "--work-dir",
+        default=None,
+        help="Precis projects work directory (default: env PRECIS_WORK_DIR or current dir)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=None,
+        help="Server port (default: 0=OS dynamic allocation; fixed port via VITE_BACKEND_PORT)",
+    )
+    parser.add_argument(
+        "--no-browser",
+        action="store_true",
+        help="Do not automatically open browser",
+    )
+    return parser.parse_args()
+
+
+def _resolve_work_dir(arg_work_dir: str | None) -> str:
+    """确定工作目录：CLI 参数 > 环境变量 > 用户配置 > 当前目录。"""
+    if arg_work_dir:
+        return os.path.abspath(arg_work_dir)
+
+    env_dir = os.environ.get("PRECIS_WORK_DIR")
+    if env_dir:
+        return os.path.abspath(env_dir)
+
+    config_path = Path.home() / ".precis" / "config.yaml"
+    if config_path.exists():
+        try:
+            import yaml
+
+            with open(config_path, encoding="utf-8") as f:
+                config = yaml.safe_load(f)
+            if isinstance(config, dict) and "work_dir" in config:
+                work_dir_value = config["work_dir"]
+                if isinstance(work_dir_value, str):
+                    return os.path.abspath(work_dir_value)
+        except Exception:
+            pass
+
+    return os.path.abspath(".")
+
+
+def _resolve_port(arg_port: int | None) -> int:
+    """确定端口：委托给 server.resolve_port(CLI 参数 > 环境变量 > 默认 0)。
+
+    0 表示交由 OS 动态分配。
+    """
+    return resolve_port(arg_port)
+
+
+def main() -> int:
+    """Main entry point for precis-start."""
+    args = _parse_args()
+    work_dir = _resolve_work_dir(args.work_dir)
+    preferred_port = _resolve_port(args.port)
+
+    if not os.path.isdir(work_dir):
+        print(f"错误：工作目录不存在: {work_dir}", file=sys.stderr)
+        return 1
+
+    # OS 原子分配端口(preferred_port=0 时动态分配),并写入端口文件供外部发现
+    actual_port = acquire_port(preferred_port)
+    write_port_file(actual_port)
+    # 传递给 uvicorn --reload 子进程,app 启动时据此自愈重写端口文件(见 api/main.py)
+    os.environ["PRECIS_BACKEND_PORT_ACTUAL"] = str(actual_port)
+    # 注册端口文件清理兜底(atexit + signal)
+    register_port_file_cleanup()
+
+    print(f"  ✓ Work directory: {work_dir}")
+    print(f"  ✓ Port: {actual_port}")
+
+    # Scan and count projects
+    project_count = 0
+    if os.path.isdir(work_dir):
+        for entry in os.scandir(work_dir):
+            if entry.is_dir():
+                manifest = os.path.join(entry.path, "project.precis.yaml")
+                if os.path.isfile(manifest):
+                    project_count += 1
+    print(f"  ✓ Found {project_count} project(s)")
+
+    # Inject work_dir into app state via environment variable
+    os.environ["PRECIS_WORK_DIR"] = work_dir
+
+    url = f"http://localhost:{actual_port}"
+
+    # §4.9: 浏览器在服务就绪后才打开——原实现先开浏览器再起 uvicorn，首开大概率
+    # "连接被拒绝"。后台线程轮询端口就绪后 open（uvicorn.run 阻塞主线程）。
+    def _open_browser_when_ready() -> None:
+        import socket
+        import time as _time
+
+        for _ in range(150):  # 最长等 75s
+            try:
+                with socket.create_connection(("127.0.0.1", actual_port), timeout=0.5):
+                    if not args.no_browser:
+                        print(f"\n  → Opening browser at {url}")
+                        webbrowser.open(url)
+                    return
+            except OSError:
+                _time.sleep(0.5)
+
+    import threading
+
+    browser_thread = threading.Thread(target=_open_browser_when_ready, daemon=True)
+    browser_thread.start()
+
+    print("\n  Server starting... (Ctrl+C to stop)")
+    print(f"  {url}")
+    print()
+
+    try:
+        # Start uvicorn server
+        import uvicorn
+
+        uvicorn.run(
+            "app.api.main:app",
+            host=DEFAULT_BACKEND_HOST,
+            port=actual_port,
+            log_level="info",
+        )
+    finally:
+        # 退出时清理端口文件
+        clear_port_file()
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

app/cli_main.py

@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# backend/app/cli_main.py
+"""
+@fileoverview Precis CLI 入口模块
+
+功能概述:
+- 提供 `python app/cli_main.py` 直接启动交互式 CLI Shell 的能力
+- 配置 PYTHONDONTWRITEBYTECODE 禁止生成字节码缓存
+- 自动将 backend 目录加入 Python 路径
+
+架构设计:
+- 兼容两种启动方式: 直接运行与模块运行 (-m)
+- 委托给 cli.shell.main 执行交互式 Shell 主循环
+
+输入示例:
+    python app/cli_main.py
+
+输出示例:
+    Precis CLI Shell 交互式界面
+"""
+
+import os
+
+os.environ.setdefault("PYTHONDONTWRITEBYTECODE", "1")
+
+import sys
+
+backend_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if backend_dir not in sys.path:
+    sys.path.insert(0, backend_dir)
+
+try:
+    from cli.shell.main import main
+except ImportError:
+    from app.cli.shell.main import main
+
+if __name__ == "__main__":
+    sys.exit(main())