precis-cli 0.1.3__py3-none-any.whl

app/cli/shell/interactive_menu.py

@@ -0,0 +1,348 @@
+# 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.
+"""
+@fileoverview CLI 交互式菜单模块
+
+功能概述:
+- 提供支持方向键导航的终端菜单选择功能
+- 支持菜单项高亮、Enter 确认、ESC/0 取消
+- 支持带状态信息的菜单显示
+
+架构设计:
+- MenuItem 封装菜单项的键、标签和描述
+- InteractiveMenu 使用 readchar 捕获键盘输入
+- 通过 ANSI 控制码实现菜单的动态渲染与清除
+"""
+
+import sys
+
+import readchar
+
+
+class MenuItem:
+    """菜单项"""
+
+    def __init__(self, key: str, label: str, description: str = ""):
+        self.key = key  # 用于返回的标识
+        self.label = label  # 显示的文本
+        self.description = description  # 描述（可选）
+
+
+class InteractiveMenu:
+    """交互式菜单
+
+    支持方向键导航、Enter 确认、ESC/0 取消。
+
+    使用示例:
+        menu = InteractiveMenu("请选择操作:")
+        menu.add_item("chat", "💬 chat", "进入交互式对话模式")
+        menu.add_item("status", "📊 status", "查看 AI 配置状态")
+        menu.add_item("switch", "🔄 switch", "切换 AI Provider")
+        menu.add_item("help", "❓ help", "显示帮助信息")
+
+        result = menu.show()
+        if result:
+            print(f"选择了: {result}")
+    """
+
+    # ANSI 控制码
+    CLEAR_LINE = "\r\033[K"  # 清除当前行（回到行首并清除到行尾）
+    MOVE_UP = "\033[{n}A"  # 向上移动 n 行
+    HIDE_CURSOR = "\033[?25l"  # 隐藏光标
+    SHOW_CURSOR = "\033[?25h"  # 显示光标
+
+    # 颜色代码
+    COLOR_RESET = "\033[0m"
+    COLOR_HIGHLIGHT = "\033[7m"  # 反色（高亮）
+    COLOR_GREEN = "\033[32m"
+    COLOR_YELLOW = "\033[33m"
+    COLOR_GRAY = "\033[90m"
+
+    def __init__(self, title: str = "", show_cancel: bool = True):
+        self.title = title
+        self.items: list[MenuItem] = []
+        self.show_cancel = show_cancel
+        self.selected_index = 0
+
+    def add_item(self, key: str, label: str, description: str = "") -> "InteractiveMenu":
+        """添加菜单项"""
+        self.items.append(MenuItem(key, label, description))
+        return self
+
+    def _get_menu_line_count(self) -> int:
+        """计算菜单总行数（用于清除）"""
+        count = 0
+        if self.title:
+            count += 1
+        count += len(self.items)
+        if self.show_cancel:
+            count += 1
+        count += 1  # 提示行（虽然是 end="" 但清除时需要处理）
+        return count
+
+    def _clear_menu(self) -> None:
+        """清除已渲染的菜单"""
+        line_count = self._get_menu_line_count()
+        sys.stdout.write(self.MOVE_UP.format(n=line_count - 1))
+        for i in range(line_count):
+            sys.stdout.write(self.CLEAR_LINE)
+            if i < line_count - 1:
+                sys.stdout.write("\n")
+        # 清除后将光标移回第一行起始位置，防止后续渲染时产生空白行堆积
+        sys.stdout.write(self.MOVE_UP.format(n=line_count - 1))
+        sys.stdout.flush()
+
+    def _render_menu(self) -> None:
+        """渲染菜单"""
+        # 标题
+        if self.title:
+            print(f"{self.COLOR_GREEN}{self.title}{self.COLOR_RESET}")
+
+        # 菜单项
+        for i, item in enumerate(self.items):
+            num = i + 1
+            if i == self.selected_index:
+                # 高亮当前选中项（反色 + 数字）
+                prefix = f"{self.COLOR_HIGHLIGHT} {num}."
+                suffix = f"{self.COLOR_RESET}"
+            else:
+                prefix = f"  {num}."
+                suffix = ""
+
+            desc = f" {self.COLOR_GRAY}{item.description}{self.COLOR_RESET}" if item.description else ""
+            print(f"{prefix} {item.label}{suffix}{desc}")
+
+        # 取消选项
+        if self.show_cancel:
+            cancel_idx = len(self.items) + 1
+            if self.selected_index == len(self.items):
+                prefix = f"{self.COLOR_HIGHLIGHT} {cancel_idx}."
+                suffix = f"{self.COLOR_RESET}"
+            else:
+                prefix = f"  {cancel_idx}."
+                suffix = ""
+            print(f"{prefix} cancel - 返回{suffix}")
+
+        # 提示（不换行，保持在同一行）
+        print(f"{self.COLOR_GRAY}↑/↓ 选择, Enter 确认, ESC/0 取消{self.COLOR_RESET}", end="", flush=True)
+
+    def show(self) -> str | None:
+        """
+        显示菜单并等待用户选择
+
+        Returns:
+            选中项的 key，如果取消则返回 None
+        """
+        if not self.items:
+            return None
+
+        # 隐藏光标
+        sys.stdout.write(self.HIDE_CURSOR)
+        sys.stdout.flush()
+
+        try:
+            # 初始渲染
+            self._render_menu()
+
+            while True:
+                # 读取单个字符
+                key = readchar.readkey()
+
+                # ESC 或 0 取消
+                if key in (readchar.key.ESC, "0"):
+                    # 清除菜单
+                    self._clear_menu()
+                    return None
+
+                # Enter 确认
+                if key in (readchar.key.ENTER, readchar.key.CR):
+                    self._clear_menu()
+                    if self.selected_index < len(self.items):
+                        return self.items[self.selected_index].key
+                    else:
+                        return None  # 选择了 cancel
+
+                # 上箭头
+                if key == readchar.key.UP:
+                    self.selected_index = (self.selected_index - 1) % (len(self.items) + (1 if self.show_cancel else 0))
+                    self._clear_menu()
+                    self._render_menu()
+
+                # 下箭头
+                elif key == readchar.key.DOWN:
+                    self.selected_index = (self.selected_index + 1) % (len(self.items) + (1 if self.show_cancel else 0))
+                    self._clear_menu()
+                    self._render_menu()
+
+                # 数字键直接选择
+                elif key.isdigit():
+                    num = int(key)
+                    if num == 0:
+                        self._clear_menu()
+                        return None
+                    elif 1 <= num <= len(self.items):
+                        self._clear_menu()
+                        return self.items[num - 1].key
+
+        finally:
+            # 确保恢复光标
+            sys.stdout.write(self.SHOW_CURSOR)
+            sys.stdout.flush()
+
+    def show_with_status(self, status_lines: list[str]) -> str | None:
+        """
+        显示带状态信息的菜单
+
+        Args:
+            status_lines: 状态信息行列表（显示在标题下方）
+
+        Returns:
+            选中项的 key，如果取消则返回 None
+        """
+        if not self.items:
+            return None
+
+        # 隐藏光标
+        sys.stdout.write(self.HIDE_CURSOR)
+        sys.stdout.flush()
+
+        # 保存状态行数（用于清除）
+        self._status_line_count = len(status_lines)
+
+        try:
+            # 初始渲染
+            self._render_menu_with_status(status_lines)
+
+            while True:
+                key = readchar.readkey()
+
+                if key in (readchar.key.ESC, "0"):
+                    self._clear_menu_with_status(status_lines)
+                    return None
+
+                if key in (readchar.key.ENTER, readchar.key.CR):
+                    self._clear_menu_with_status(status_lines)
+                    if self.selected_index < len(self.items):
+                        return self.items[self.selected_index].key
+                    else:
+                        return None
+
+                if key == readchar.key.UP:
+                    self.selected_index = (self.selected_index - 1) % (len(self.items) + (1 if self.show_cancel else 0))
+                    self._clear_menu_with_status(status_lines)
+                    self._render_menu_with_status(status_lines)
+
+                elif key == readchar.key.DOWN:
+                    self.selected_index = (self.selected_index + 1) % (len(self.items) + (1 if self.show_cancel else 0))
+                    self._clear_menu_with_status(status_lines)
+                    self._render_menu_with_status(status_lines)
+
+                elif key.isdigit():
+                    num = int(key)
+                    if num == 0:
+                        self._clear_menu_with_status(status_lines)
+                        return None
+                    elif 1 <= num <= len(self.items):
+                        self._clear_menu_with_status(status_lines)
+                        return self.items[num - 1].key
+
+        finally:
+            sys.stdout.write(self.SHOW_CURSOR)
+            sys.stdout.flush()
+
+    def _get_menu_with_status_line_count(self, status_lines: list[str]) -> int:
+        """计算带状态信息的菜单总行数（用于清除）"""
+        count = 0
+        if self.title:
+            count += 1
+        count += len(status_lines)
+        count += len(self.items)
+        if self.show_cancel:
+            count += 1
+        count += 1
+        return count
+
+    def _render_menu_with_status(self, status_lines: list[str]) -> None:
+        """渲染带状态信息的菜单"""
+        # 标题
+        if self.title:
+            print(f"{self.COLOR_GREEN}{self.title}{self.COLOR_RESET}")
+
+        # 状态信息
+        for line in status_lines:
+            print(line)
+
+        # 菜单项
+        for i, item in enumerate(self.items):
+            num = i + 1
+            if i == self.selected_index:
+                prefix = f"{self.COLOR_HIGHLIGHT} {num}."
+                suffix = f"{self.COLOR_RESET}"
+            else:
+                prefix = f"  {num}."
+                suffix = ""
+
+            desc = f" {self.COLOR_GRAY}{item.description}{self.COLOR_RESET}" if item.description else ""
+            print(f"{prefix} {item.label}{suffix}{desc}")
+
+        # 取消选项
+        if self.show_cancel:
+            cancel_idx = len(self.items) + 1
+            if self.selected_index == len(self.items):
+                prefix = f"{self.COLOR_HIGHLIGHT} {cancel_idx}."
+                suffix = f"{self.COLOR_RESET}"
+            else:
+                prefix = f"  {cancel_idx}."
+                suffix = ""
+            print(f"{prefix} cancel - 返回{suffix}")
+
+        # 提示（不换行）
+        print(f"{self.COLOR_GRAY}↑/↓ 选择, Enter 确认, ESC/0 取消{self.COLOR_RESET}", end="", flush=True)
+
+    def _clear_menu_with_status(self, status_lines: list[str]) -> None:
+        """清除带状态信息的菜单"""
+        line_count = self._get_menu_with_status_line_count(status_lines)
+        sys.stdout.write(self.MOVE_UP.format(n=line_count - 1))
+        for i in range(line_count):
+            sys.stdout.write(self.CLEAR_LINE)
+            if i < line_count - 1:
+                sys.stdout.write("\n")
+        # 清除后将光标移回第一行起始位置，防止后续渲染时产生空白行堆积
+        sys.stdout.write(self.MOVE_UP.format(n=line_count - 1))
+        sys.stdout.flush()
+
+
+def show_simple_menu(title: str, options: list[tuple[str, str, str]]) -> str | None:
+    """
+    快速显示简单菜单
+
+    Args:
+        title: 菜单标题
+        options: [(key, label, description), ...]
+
+    Returns:
+        选中项的 key，如果取消则返回 None
+
+    示例:
+        result = show_simple_menu("请选择:", [
+            ("a", "选项 A", "这是选项 A"),
+            ("b", "选项 B", "这是选项 B"),
+        ])
+    """
+    menu = InteractiveMenu(title)
+    for key, label, desc in options:
+        menu.add_item(key, label, desc)
+    return menu.show()

app/cli/shell/main.py

@@ -0,0 +1,286 @@
+# 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/main.py
+"""
+@fileoverview CLI Shell 主循环模块
+
+功能概述:
+- 提供交互式命令行 Shell 主循环
+- 管理命令注册、解析和执行
+- 支持初始参数直接执行与持续交互模式
+
+架构设计:
+- CLIShell 类管理命令注册表和项目上下文
+- CommandParser 解析输入，CommandExecutor 执行命令
+- 支持全局快捷退出命令（exit!, quit!, qq）
+"""
+
+import logging
+import re
+import sys
+
+from app.cli.shell.commands import (
+    AICommand,
+    ConfigCommand,
+    ExitCommand,
+    HelpCommand,
+    InferSchemaCommand,
+    LsCommand,
+    OpenCommand,
+    ProjectCommand,
+    ProviderCommand,
+    PwdCommand,
+    ValidateCommand,
+)
+from app.cli.shell.commands.base import ProjectContext
+from app.cli.shell.exceptions import CLIError
+from app.cli.shell.formatter import Colors, Formatter
+from app.cli.shell.parser import CommandExecutor, CommandParser, CommandRegistry
+
+
+def _setup_logging() -> None:
+    """配置日志级别，CLI 模式下只显示警告及以上级别。"""
+    import os
+
+    debug_mode = os.environ.get("PRECIS_DEBUG", "").lower() in ("1", "true", "yes")
+    level = logging.DEBUG if debug_mode else logging.WARNING
+    logging.basicConfig(level=level, format="%(levelname)s: %(message)s", handlers=[logging.StreamHandler(sys.stderr)])
+
+
+def _setup_encoding() -> None:
+    """确保 stdout/stderr 使用 UTF-8 编码（委托 shared.core.encoding 公共助手）。"""
+    from app.shared.core.encoding import setup_utf8_console
+
+    setup_utf8_console()
+
+
+# 匹配 ANSI 颜色/样式转义序列（如 \x1b[36m、\x1b[0m）
+_ANSI_ESCAPE_RE = re.compile(r"\x1b\[[0-9;]*m")
+
+
+def _get_version() -> str:
+    """获取 CLI 版本号（委托 shared.core.app_version，供 --version 旗标）。"""
+    from app.shared.core.app_version import get_app_version
+
+    return get_app_version()
+
+
+def _wrap_ansi_for_readline(prompt: str) -> str:
+    """将 ANSI 转义序列用 readline 非打印分隔符 \\x01/\\x02 包裹。
+
+    readline/pyreadline3 计算 prompt 可见宽度时会把 ANSI 颜色码误算为可见字符，
+    导致输入行光标错位。用 \\x01...\\x02 包裹后 readline 会跳过这些序列的宽度计算。
+
+    Args:
+        prompt: 含 ANSI 转义的原始 prompt 字符串
+
+    Returns:
+        包裹后的 prompt，颜色显示不变但 readline 宽度计算正确
+    """
+    return _ANSI_ESCAPE_RE.sub(lambda m: "\x01" + m.group(0) + "\x02", prompt)
+
+
+class CLIShell:
+    """CLI Shell 主类。
+
+    管理命令注册和交互式主循环。
+    """
+
+    def __init__(self) -> None:
+        self.registry = CommandRegistry()
+        self.context = ProjectContext()
+        self._setup_commands()
+        # Tab 补全是否已激活（交互模式下由 _setup_readline 设置）
+        self._readline_active: bool = False
+
+    def _setup_commands(self) -> None:
+        """注册所有内置命令。"""
+        self.registry.register(HelpCommand(self.registry))
+        self.registry.register(OpenCommand())
+        self.registry.register(ProjectCommand())
+        self.registry.register(ValidateCommand())
+        self.registry.register(InferSchemaCommand())
+        self.registry.register(ConfigCommand())
+        self.registry.register(ProviderCommand())
+        self.registry.register(AICommand())
+        self.registry.register(PwdCommand())
+        self.registry.register(LsCommand())
+        self.registry.register(ExitCommand())
+
+    def run(self, initial_args: list | None = None) -> int:
+        """运行 CLI Shell。
+
+        Args:
+            initial_args: 初始参数，如果提供则执行后退出
+
+        Returns:
+            退出码
+        """
+        parser = CommandParser(self.registry)
+        executor = CommandExecutor(parser, self.context)
+
+        if initial_args:
+            input_line = " ".join(initial_args)
+            # 全局快捷退出命令
+            if input_line.lower() in ("exit!", "quit!", "qq"):
+                print(Formatter.success("再见!"))
+                sys.exit(0)
+            result = executor.execute_with_args(initial_args)
+            if result.message:
+                if result.success:
+                    print(result.message)
+                else:
+                    Formatter.print_error(result.message)
+            # 单发模式退出码契约：0 = 校验通过；1 = 校验完成但发现数据违规；
+            # 2 = 工具自身错误（参数错误、文件不存在、异常崩溃）。
+            # 命令显式携带 exit_code 时优先（如 validate 的清单不存在传 2），
+            # 其余按 success 推导（成功 0 / 失败 1）。这对 CI/CD 与 agent
+            # 自动化至关重要：仅凭退出码即可区分红绿与工具故障。
+            if result.exit_code is not None:
+                return result.exit_code
+            return 0 if result.success else 1
+
+        Formatter.print_welcome()
+
+        # 交互模式：尝试安装 Tab 补全（无 readline 后端时静默降级）
+        self._readline_active = self._setup_readline()
+
+        while True:
+            try:
+                prompt = self._get_prompt()
+                # 主循环使用普通 input 保持颜色，get_input_cached 只用于 AI chat
+                input_line = input(prompt).strip()
+
+                if not input_line:
+                    continue
+
+                # 全局快捷退出命令
+                if input_line.lower() in ("exit!", "quit!", "qq"):
+                    print(Formatter.success("再见!"))
+                    sys.exit(0)
+
+                exit_code = self._execute_line(executor, input_line)
+
+                if exit_code != 0:
+                    # _execute_line 的非 0 仅是 should_exit 的循环哨兵（用户主动 exit），
+                    # 属正常退出——进程退出码必须为 0，与 qq/EOF 路径一致。
+                    # 原实现把哨兵透传为进程退出码，脚本化 `echo exit | precis` 会被误判为失败。
+                    return 0
+
+            except KeyboardInterrupt:
+                print()
+                print(Formatter.info("使用 'exit' 或 'quit' 退出，'qq' 直接退出程序"))
+            except EOFError:
+                print()
+                print(Formatter.success("再见!"))
+                return 0
+
+    def _execute_line(self, executor: CommandExecutor, input_line: str) -> int:
+        """执行一行输入。
+
+        Args:
+            executor: 命令执行器
+            input_line: 输入行
+
+        Returns:
+            退出码，0 表示继续， 非0 表示退出
+        """
+        result = executor.execute(input_line)
+
+        if result.message:
+            if result.success:
+                print(result.message)
+            else:
+                Formatter.print_error(result.message)
+
+        if result.should_exit:
+            return 1
+
+        return 0
+
+    def _get_prompt(self) -> str:
+        """获取命令提示符。
+
+        当 Tab 补全激活时（readline 后端接管 input），将 ANSI 转义序列用
+        \\x01/\\x02 非打印分隔符包裹，避免 readline/pyreadline3 计算 prompt
+        宽度时把颜色码计入可见字符导致光标错位。
+        """
+        if self.context.is_project_open:
+            # project_config 在 open 命令后可能尚未加载（OpenCommand 只设置 project_path），
+            # 此处做空值守卫避免 AttributeError 导致 Shell 崩溃退出。
+            config = self.context.project_config or {}
+            project_name = config.get("project", {}).get("name", "project")
+            prompt = Formatter.colorize(f"precis:{project_name}> ", Colors.CYAN)
+        else:
+            prompt = Formatter.colorize("precis> ", Colors.CYAN)
+
+        if self._readline_active:
+            return _wrap_ansi_for_readline(prompt)
+        return prompt
+
+    def _setup_readline(self) -> bool:
+        """安装 Tab 补全到 readline 后端。
+
+        仅在交互模式下调用。Windows 用 pyreadline3，Unix 用 stdlib readline，
+        两者均不可用时返回 False（REPL 照常运行，仅无补全）。
+
+        Returns:
+            True 表示补全已激活；False 表示降级为无补全模式
+        """
+        # 延迟导入：避免在单次执行模式（非交互）下加载补全模块的依赖
+        from app.cli.shell.completer import install_readline_completer
+
+        try:
+            return install_readline_completer(self.registry)
+        except Exception:
+            # 任何意外异常都不应阻断 REPL 启动
+            return False
+
+
+def main(args: list | None = None) -> int:
+    """CLI 主入口函数。
+
+    Args:
+        args: 命令行参数列表，默认为 sys.argv[1:]
+
+    Returns:
+        退出码
+    """
+    _setup_encoding()
+    _setup_logging()
+
+    if args is None:
+        args = sys.argv[1:]
+
+    # 全局版本旗标：独立于命令体系，供外部集成（如 Kimi Code 插件）探测 CLI 可用性
+    if args and args[0] in ("--version", "-v"):
+        print(f"precis {_get_version()}")
+        return 0
+
+    try:
+        shell = CLIShell()
+        return shell.run(args)
+    except CLIError as e:
+        Formatter.print_error(e.message)
+        return e.exit_code
+    except Exception as e:
+        # 未预期崩溃属工具自身错误，退出码 2（区别于"校验发现数据违规"的 1）
+        Formatter.print_error(f"未预期的错误: {e}")
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())