precis-cli 0.1.3__py3-none-any.whl

app/cli/shell/completer.py

@@ -0,0 +1,231 @@
+# 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/completer.py
+"""
+@fileoverview CLI Shell Tab 补全模块
+
+功能概述:
+- 为交互式 REPL 提供命令名 + 子命令名的 Tab 补全
+- Windows 使用 pyreadline3，Unix 使用 stdlib readline，两者均不可用时静默降级
+- 通过 readline 的 completer 协议接入原生 input()
+
+架构设计:
+- install_readline_completer(): 导入 readline 后端并注册补全函数，返回是否成功
+- _make_completer(): 工厂函数，返回符合 readline 协议的 complete(text, state) 闭包
+- 补全分两层：顶层命令（含别名）/ 子命令（含别名）
+
+输入示例（REPL 内）:
+    precis> val<Tab>         → validate
+    precis> che<Tab>         → check（validate 别名）
+    precis> project <Tab>    → 列出 open/status/history
+
+输出示例:
+    install_readline_completer(registry) -> True  # 成功注册
+    install_readline_completer(registry) -> False # 无可用 readline 后端，降级
+"""
+
+from __future__ import annotations
+
+import importlib
+from collections.abc import Callable
+from types import ModuleType
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    # 仅用于类型注解（from __future__ annotations 使注解为字符串），
+    # 运行时无需导入，避免与 parser→commands→parser 的循环导入。
+    from app.cli.shell.parser import CommandRegistry
+
+
+def _import_readline() -> ModuleType | None:
+    """导入 readline 后端。
+
+    Unix 上 stdlib readline 可用；Windows 上 stdlib 无 readline，
+    退回到 pyreadline3（需 pip install pyreadline3 或 precis[completion]）。
+
+    Returns:
+        readline 模块对象；两者都不可用时返回 None
+    """
+    # Unix: stdlib readline（部分 Windows 构建如 Anaconda 也可能内置）；
+    # Windows 退回 pyreadline3（与 stdlib readline 接口兼容）
+    for module_name in ("readline", "pyreadline3"):
+        try:
+            return importlib.import_module(module_name)
+        except ImportError:
+            continue
+    return None
+
+
+def install_readline_completer(registry: CommandRegistry) -> bool:
+    """安装 Tab 补全到 readline 后端。
+
+    配置 tab: complete、设置分词分隔符、注册补全函数。
+    仅在交互 REPL 启动时调用一次。
+
+    Args:
+        registry: 命令注册表，补全函数据此提供候选
+
+    Returns:
+        True 表示成功注册（补全可用）；
+        False 表示无可用 readline 后端，调用方应降级为无补全模式
+    """
+    readline = _import_readline()
+    if readline is None:
+        return False
+
+    # tab 键触发补全（标准 readline 配置）
+    readline.parse_and_bind("tab: complete")
+    # 命令/子命令补全按空格分词，不依赖标点等其他分隔符
+    readline.set_completer_delims(" \t\n")
+    # 注册补全函数
+    readline.set_completer(_make_completer(registry))
+    return True
+
+
+def _make_completer(registry: CommandRegistry) -> Callable[[str, int], str | None]:
+    """构造 readline completer 闭包。
+
+    readline 协议：对同一 text 反复调用，state 从 0 递增，
+    依次返回匹配候选，耗尽后返回 None。
+
+    Args:
+        registry: 命令注册表
+
+    Returns:
+        complete(text, state) -> Optional[str] 函数
+    """
+    # 每次补全会话缓存候选列表，避免每个 state 重复计算
+    # （readline 对同一 text 调用 complete(text,0..N)，state=0 时重建列表）
+    cached: dict[str, list[str]] = {}
+
+    def complete(text: str, state: int) -> str | None:
+        # 延迟导入 readline：测试时可用 monkeypatch 替换 get_line_buffer
+        readline = _import_readline()
+        if readline is None:
+            return None
+
+        # state=0 表示新一轮补全，重建候选缓存
+        if state == 0:
+            cached[text] = _compute_candidates(registry, readline, text)
+
+        candidates = cached.get(text, [])
+        if state < len(candidates):
+            return candidates[state]
+        return None
+
+    return complete
+
+
+def _compute_candidates(registry: CommandRegistry, readline: ModuleType, text: str) -> list[str]:
+    """计算当前补全候选列表。
+
+    两层补全逻辑：
+    - 顶层：line_buffer 未出现已完成（带空格）的命令 → 候选为所有命令名+别名
+    - 子命令层：line_buffer 首词匹配到有子命令的命令 → 候选为该命令的子命令名+别名
+    - 其他（无子命令的命令，或已输入到第三词及以后）→ 空列表（不补全）
+
+    Args:
+        registry: 命令注册表
+        readline: readline 后端（用于 get_line_buffer）
+        text: 当前正在输入的 token（readline 传入）
+
+    Returns:
+        匹配候选列表，已按字典序排序；每项在完整匹配时追加尾部空格
+    """
+    try:
+        line_buffer = readline.get_line_buffer()
+    except Exception:
+        # get_line_buffer 不可用时退化为仅用 text 做顶层补全
+        line_buffer = text
+
+    # 判断是否处于"正在输入第一个词"阶段：
+    # 若 line_buffer 去除尾部 text 后不含空格，说明还在第一个词
+    buffer_before_text = line_buffer[: len(line_buffer) - len(text)]
+    in_first_word = buffer_before_text.strip() == ""
+
+    if in_first_word:
+        # 顶层命令补全（含别名）
+        return _filter_and_decorate(_collect_top_level(registry), text)
+
+    # 已完成第一个词，尝试子命令补全。
+    # 关键：区分"已完成词"与"正在输入的词"。line_buffer 末尾若无空格，
+    # 说明最后那个 token 就是当前正在输入的词（即 text），不计入已完成词。
+    all_tokens = line_buffer.split()
+    trailing_space = line_buffer.endswith(" ")
+    # 已完成的词数：末尾有空格 → all_tokens 全是已完成；否则最后一个正在输入
+    completed_tokens = all_tokens if trailing_space else all_tokens[:-1]
+
+    first_word = completed_tokens[0] if completed_tokens else ""
+    command = registry.get(first_word)
+    if command is None:
+        return []
+
+    sub_names = command.list_subcommands()
+    if not sub_names:
+        # 该命令无子命令，不补全（参数/路径补全留给未来）
+        return []
+
+    # 仅当"正在输入第二个词"（completed_tokens 恰好 1 个）才补全子命令；
+    # 若已完成 2 个及以上词，说明在输第三词或更后，不再补全子命令。
+    if len(completed_tokens) >= 2:
+        return []
+
+    candidates: list[str] = []
+    for sub_name in sub_names:
+        candidates.append(sub_name)
+        sub_cmd = command.get_subcommand(sub_name)
+        if sub_cmd is not None:
+            candidates.extend(sub_cmd.aliases)
+
+    return _filter_and_decorate(candidates, text)
+
+
+def _collect_top_level(registry: CommandRegistry) -> list[str]:
+    """收集所有顶层命令名 + 别名。"""
+    names: list[str] = []
+    for cmd in registry.get_all_commands():
+        names.append(cmd.name)
+        names.extend(cmd.aliases)
+    return names
+
+
+def _filter_and_decorate(candidates: list[str], text: str) -> list[str]:
+    """过滤出以 text 开头的候选，去重排序，并对完整匹配项追加尾部空格。
+
+    readline 在单候选时会自动补全到完整词；追加空格让用户补全命令名后
+    可直接继续输入子命令/参数，符合 shell 惯例。
+
+    Args:
+        candidates: 原始候选列表（可能含重复）
+        text: 前缀过滤条件
+
+    Returns:
+        处理后的候选列表
+    """
+    seen: set[str] = set()
+    matched: list[str] = []
+    for c in candidates:
+        if c.startswith(text) and c not in seen:
+            seen.add(c)
+            # 完整匹配（text 非空且等于候选）时追加空格；
+            # 前缀补全（text 是候选的前缀）由 readline 自动补齐，也加空格提升体验
+            matched.append(c + " " if text else c)
+    matched.sort()
+    return matched
+
+
+# Command 仅用于类型注解引用，避免 ruff 报未使用导入
+__all__ = ["install_readline_completer", "_import_readline", "_make_completer", "_compute_candidates"]

app/cli/shell/config_storage.py

@@ -0,0 +1,191 @@
+# 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 AI 配置存储模块
+
+功能概述:
+- 适配 LLM 配置系统，管理 ~/.precis/ai_providers.yaml
+- 提供 Provider 的增删改查与默认设置切换
+- 支持配置热重载
+
+架构设计:
+- CLIConfigStorage 封装 AIConfig 的加载与持久化
+- 直接使用 AIProvider 模型，与 API 层保持一致
+- 单例模式通过 get_cli_config() 提供全局访问
+"""
+
+from __future__ import annotations
+
+from app.shared.services.llm.config.loader import loader
+from app.shared.services.llm.config.models import AIConfig, AIProvider
+
+
+class CLIConfigStorage:
+    """CLI 配置存储管理类（直接使用 AIProvider 模型）"""
+
+    def __init__(self) -> None:
+        self._config: AIConfig
+        self._loaded_mtime: float | None = None
+        # §4.2: 启动即 strict——providers YAML 损坏时 fail-fast（明确报错+退出），
+        # 不再静默回退空配置（此前 add/save 会把空配置覆盖写盘，原配置彻底销毁）
+        self._load(strict=True)
+
+    def _load(self, strict: bool = False) -> None:
+        """从文件加载配置。
+
+        Args:
+            strict: 严格模式。为 True 时解析失败抛携带修复指引的 RuntimeError；
+                为 False（默认）时静默回退到空 AIConfig（运行时 reload 容错语义）。
+        """
+        try:
+            self._config = loader.load()
+            try:
+                self._loaded_mtime = loader.config_path.stat().st_mtime
+            except OSError:
+                self._loaded_mtime = None
+        except Exception as e:
+            if strict:
+                # §4.2: 携带文件路径与修复指引的明确错误（调用方以非 0 退出呈现）
+                config_path = getattr(loader, "config_path", None)
+                raise RuntimeError(
+                    f"AI Provider 配置文件损坏，已阻止启动以防空配置覆盖写盘：\n"
+                    f"  文件: {config_path}\n"
+                    f"  错误: {e}\n"
+                    f"  修复: 手工修正 YAML 语法后重试；或备份后删除该文件重新 setup"
+                ) from e
+            self._config = AIConfig()
+
+    def _save(self) -> None:
+        """保存配置到文件。
+
+        §4.10: 写前 mtime 校验（读-改-写丢更新防护）——本实例加载后文件被其他进程
+        （TUI/Electron/另一 CLI 会话）修改过则拒绝写入并提示，避免后写覆盖先写。
+        """
+        try:
+            current_mtime = loader.config_path.stat().st_mtime
+            if self._loaded_mtime is not None and current_mtime != self._loaded_mtime:
+                raise RuntimeError(
+                    "配置已被其他进程修改（CLI/TUI/Electron 并发编辑），请重新进入本会话加载最新配置后再修改"
+                )
+        except OSError:
+            pass  # 文件尚不存在（首次写入）等场景直接尝试保存
+        loader.save(self._config)
+        try:
+            self._loaded_mtime = loader.config_path.stat().st_mtime
+        except OSError:
+            self._loaded_mtime = None
+
+    def get_provider(self, provider_id: str) -> AIProvider | None:
+        """获取指定 Provider"""
+        for p in self._config.providers:
+            if p.id == provider_id:
+                return p
+        return None
+
+    def get_active_provider(self) -> AIProvider | None:
+        """获取当前活动的 Provider"""
+        # 从 defaults 中获取默认 chat provider
+        default_id = self._config.defaults.get("chat")
+        if default_id:
+            return self.get_provider(default_id)
+        # 如果没有设置，返回第一个
+        if self._config.providers:
+            return self._config.providers[0]
+        return None
+
+    def set_active_provider(self, provider_id: str) -> bool:
+        """设置活动 Provider"""
+        if not any(p.id == provider_id for p in self._config.providers):
+            return False
+        self._config.defaults["chat"] = provider_id
+        self._save()
+        return True
+
+    def add_or_update_provider(self, provider: AIProvider) -> None:
+        """添加或更新 Provider"""
+        # 查找并替换或添加
+        for i, p in enumerate(self._config.providers):
+            if p.id == provider.id:
+                self._config.providers[i] = provider
+                break
+        else:
+            self._config.providers.append(provider)
+
+        # 如果是第一个 provider，设为默认
+        if len(self._config.providers) == 1:
+            self._config.defaults["chat"] = provider.id
+
+        self._save()
+
+    def mark_api_key_manual(self, provider_id: str) -> None:
+        """把 provider 的 api_key 标记为手工设置（§2.12：save 时不再按 env 来源剔除落盘）。
+
+        CLI 的 add/edit 路径在用户显式输入 API Key 后、落盘前调用——否则该 provider
+        若存在同名环境变量（<ID>_API_KEY），save() 会把用户刚输入的 key 当 env 来源
+        剔除，新 key 永不落盘（env 移除后 provider 无 key 可用）。
+        """
+        loader.mark_api_key_manual(provider_id)
+
+    def list_providers(self) -> list[AIProvider]:
+        """列出所有 Providers"""
+        return list(self._config.providers)
+
+    def has_configured_provider(self) -> bool:
+        """检查是否有已配置的 Provider（有 API Key）"""
+        for p in self._config.providers:
+            if p.api_key:
+                return True
+        return False
+
+    def delete_provider(self, provider_id: str) -> bool:
+        """删除 Provider"""
+        original_len = len(self._config.providers)
+        self._config.providers = [p for p in self._config.providers if p.id != provider_id]
+        if len(self._config.providers) < original_len:
+            if self._config.defaults.get("chat") == provider_id:
+                self._config.defaults["chat"] = ""
+            self._save()
+            return True
+        return False
+
+
+# 全局配置存储实例
+_cli_config = None
+
+
+def get_cli_config() -> CLIConfigStorage:
+    """获取 CLI 配置存储实例（单例）"""
+    global _cli_config
+    if _cli_config is None:
+        _cli_config = CLIConfigStorage()
+    return _cli_config
+
+
+def reload_providers_config() -> bool:
+    """重新加载 Provider 配置。
+
+    Returns:
+        重载成功返回 True；配置文件损坏/格式非法导致解析失败时返回 False，
+        调用方据此提示用户检查文件格式（如 provider reload 命令的错误分支）。
+    """
+    global _cli_config
+    if _cli_config:
+        loader.invalidate_cache()
+        try:
+            _cli_config._load(strict=True)
+        except Exception:
+            return False
+    return True

app/cli/shell/exceptions.py

@@ -0,0 +1,90 @@
+# 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/exceptions.py
+"""
+@fileoverview CLI Shell 自定义异常模块
+
+功能概述:
+- 定义 CLI 交互式界面中使用的自定义异常类型
+- 为不同错误场景提供特定的退出码
+- 所有异常继承自 CLIError 基类
+
+架构设计:
+- CLIError 作为基础异常，包含消息和退出码
+- 派生异常覆盖特定场景：项目未找到、命令未找到、验证失败等
+"""
+
+
+class CLIError(Exception):
+    """CLI 基础异常类。"""
+
+    def __init__(self, message: str, exit_code: int = 1):
+        super().__init__(message)
+        self.message = message
+        self.exit_code = exit_code
+
+
+class ProjectNotFoundError(CLIError):
+    """项目目录未找到异常。"""
+
+    def __init__(self, path: str):
+        super().__init__(f"项目目录未找到: {path}", exit_code=2)
+        self.path = path
+
+
+class InvalidProjectError(CLIError):
+    """无效的项目目录异常。"""
+
+    def __init__(self, path: str, reason: str):
+        super().__init__(f"无效的项目目录: {path}, 原因: {reason}", exit_code=3)
+        self.path = path
+        self.reason = reason
+
+
+class NoProjectOpenError(CLIError):
+    """未打开项目异常。"""
+
+    def __init__(self) -> None:
+        super().__init__("未打开项目，请使用 'open <path>' 命令打开项目", exit_code=4)
+
+
+class CommandNotFoundError(CLIError):
+    """命令未找到异常。"""
+
+    def __init__(self, command: str):
+        super().__init__(f"命令未找到: {command}", exit_code=5)
+        self.command = command
+
+
+class ValidationError(CLIError):
+    """验证执行异常。"""
+
+    def __init__(self, message: str):
+        super().__init__(f"验证执行失败: {message}", exit_code=6)
+
+
+class ConfigError(CLIError):
+    """配置文件操作异常。"""
+
+    def __init__(self, message: str):
+        super().__init__(f"配置文件操作失败: {message}", exit_code=7)
+
+
+class EditorError(CLIError):
+    """编辑器调用异常。"""
+
+    def __init__(self, message: str):
+        super().__init__(f"编辑器调用失败: {message}", exit_code=8)