precis-cli 0.1.3__py3-none-any.whl

app/cli/shared_services/generation_ops.py

@@ -0,0 +1,160 @@
+# 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/shared_services/generation_ops.py
+"""
+@fileoverview 生成/迁移配置落盘共享逻辑（CLI/TUI 同源）
+
+功能概述:
+- 收敛 AI 配置生成与迁移的纯业务逻辑：生成结果落盘、数据文件扫描与展开
+- 供 CLI 的 ai generate / ai migrate 命令与未来 TUI 的生成/迁移屏共同调用
+
+架构设计:
+- 本模块只含纯逻辑与文件 IO，不含任何 UI/交互
+- apply_generated_config 复用 V2 配置写入约定（project.precis.yaml + schemas/ + constraints/ + regex/）
+- scan_data_files 统一 patterns 展开与 data/ 目录扫描两种入口
+
+接口契约（P0b 冻结）:
+    def apply_generated_config(result: dict, project_path: str) -> list[str]
+    def scan_data_files(patterns: list[str], project_path: str) -> list[str]
+"""
+
+from __future__ import annotations
+
+import glob
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+from app.shared.core.io.yaml import read_yaml, write_yaml_atomic
+
+logger = logging.getLogger(__name__)
+
+# 支持的文件扩展名（generate/migrate 共用）
+SUPPORTED_EXTENSIONS = (".xlsx", ".xls", ".csv", ".json", ".jsonl")
+
+
+def scan_data_files(patterns: list[str], project_path: str) -> list[str]:
+    """展开数据文件路径（支持通配符、相对路径、data/ 目录扫描）。
+
+    逻辑：
+    1. 若 patterns 非空：逐个展开通配符 / 直连存在的路径，合并去重
+    2. 若 patterns 为空（或展开后为空）：扫描项目 data/ 目录下的支持文件
+    3. 最终按 SUPPORTED_EXTENSIONS 过滤
+
+    Args:
+        patterns: 用户输入的文件模式列表（可为相对项目根的路径或通配符）
+        project_path: 项目根目录绝对路径
+
+    Returns:
+        绝对路径列表（已去重、已排序的 data/ 扫描部分 + 保持展开顺序的 patterns 部分）
+    """
+    file_paths: list[str] = []
+    for pattern in patterns:
+        if not os.path.isabs(pattern):
+            pattern = os.path.join(project_path, pattern)
+        matched = glob.glob(pattern)
+        if matched:
+            file_paths.extend(matched)
+        elif os.path.exists(pattern):
+            file_paths.append(pattern)
+
+    # 合并去重（保序）
+    file_paths = list(dict.fromkeys(file_paths))
+
+    # 无文件参数时扫描 data/ 目录（保持原 _scan_data_files 行为）
+    if not file_paths:
+        data_dir = Path(project_path) / "data"
+        if data_dir.exists():
+            for ext in SUPPORTED_EXTENSIONS:
+                file_paths.extend(str(p) for p in data_dir.glob(f"*{ext}"))
+            # 扫描分支输出排序，保证结果稳定
+            file_paths.sort()
+
+    # 过滤支持的文件类型
+    return [p for p in file_paths if p.lower().endswith(SUPPORTED_EXTENSIONS)]
+
+
+def apply_generated_config(result: dict[str, Any], project_path: str) -> list[str]:
+    """将生成的配置写入项目目录。
+
+    会保留现有 project.precis.yaml 中的 transforms/manual_data 等引用，
+    覆盖写入 schemas、constraints、regex_nodes。
+
+    Args:
+        result: ConfigGenerationService / ConfigMigrationService 返回的配置字典
+        project_path: 项目根目录
+
+    Returns:
+        已写入的文件相对路径列表（manifest + 各 schema/constraint/regex 文件）
+    """
+    written: list[str] = []
+
+    manifest_path = Path(project_path) / "project.precis.yaml"
+    existing_manifest: dict[str, Any] = {}
+    if manifest_path.exists():
+        try:
+            existing_manifest = read_yaml(manifest_path) or {}
+        except Exception:
+            logger.warning("读取现有 manifest 失败，将覆盖写入", exc_info=True)
+
+    manifest = result.get("manifest") or {"version": 2, "project": {"id": "", "name": ""}}
+
+    # 保留现有 manifest 中生成未覆盖的引用
+    for key in ("transforms", "manual_data"):
+        if key in existing_manifest and key not in manifest:
+            manifest[key] = existing_manifest[key]
+
+    schemas = result.get("schemas", {})
+    constraints = result.get("constraints", {})
+    regex_nodes = result.get("regex_nodes", {})
+
+    # 确保目录存在
+    (Path(project_path) / "schemas").mkdir(exist_ok=True)
+    (Path(project_path) / "constraints").mkdir(exist_ok=True)
+    (Path(project_path) / "regex").mkdir(exist_ok=True)
+
+    # 更新 manifest 引用
+    manifest["schemas"] = [{"id": sid, "path": f"schemas/{sid}.schema.yaml"} for sid in schemas]
+    manifest["constraints"] = [{"id": cid, "path": f"constraints/{cid}.constraint.yaml"} for cid in constraints]
+    manifest["regex_nodes"] = [{"id": rid, "path": f"regex/{rid}.regex.yaml"} for rid in regex_nodes]
+
+    # 写入 manifest
+    write_yaml_atomic(manifest_path, manifest)
+    written.append("project.precis.yaml")
+
+    # 写入资源文件
+    for sid, schema in schemas.items():
+        rel = f"schemas/{sid}.schema.yaml"
+        write_yaml_atomic(Path(project_path) / rel, schema)
+        written.append(rel)
+    for cid, constraint in constraints.items():
+        rel = f"constraints/{cid}.constraint.yaml"
+        write_yaml_atomic(Path(project_path) / rel, constraint)
+        written.append(rel)
+    for rid, regex_node in regex_nodes.items():
+        rel = f"regex/{rid}.regex.yaml"
+        write_yaml_atomic(Path(project_path) / rel, regex_node)
+        written.append(rel)
+
+    return written
+
+
+__all__ = [
+    "SUPPORTED_EXTENSIONS",
+    "apply_generated_config",
+    "scan_data_files",
+]

app/cli/shared_services/project_ops.py

@@ -0,0 +1,288 @@
+# 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/shared_services/project_ops.py
+"""
+@fileoverview 项目操作共享逻辑（CLI/TUI 同源）
+
+功能概述:
+- 收敛「打开项目」相关的纯业务逻辑：历史记录读写、清单定位与加载、项目显示名解析
+- 供 CLI 的 open 命令与未来 TUI 的项目管理屏共同调用，确保「改一处即可」
+
+架构设计:
+- 本模块只含纯逻辑与文件 IO，不含任何 UI/交互（InteractiveMenu 等留在各 UI 层）
+- 历史记录持久化到 ~/.precis_project_history，去重 + MAX_HISTORY 容量上限
+- 清单加载复用 shared/core 的 load_manifest，保证解析与系统其余部分一致
+
+接口契约（P0b 冻结）:
+    def load_history() -> list[dict]
+    def add_to_history(project_path: str) -> None
+    def find_manifest(project_path: str) -> str | None
+    def load_manifest_config(manifest_path: str) -> dict | None
+    def resolve_project_label(project_path: str) -> str
+    def open_project(project_path: str) -> OpenResult
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+logger = logging.getLogger(__name__)
+
+# 历史记录文件路径：存储在用户主目录下
+HISTORY_FILE = os.path.expanduser("~/.precis_project_history")
+# 最大历史记录数量，超过时会自动丢弃最旧的项目
+MAX_HISTORY = 10
+
+
+def load_history() -> list[dict]:
+    """加载项目打开历史。
+
+    从 HISTORY_FILE 读取历史记录。文件不存在、格式损坏或权限不足时返回空列表。
+
+    Returns:
+        历史记录列表，每个元素为包含 path 和 last_opened 的字典
+    """
+    if not os.path.exists(HISTORY_FILE):
+        return []
+    try:
+        with open(HISTORY_FILE, encoding="utf-8") as f:
+            data = json.load(f)
+            if isinstance(data, list):
+                # 4.8: 条目级健壮性——磁盘问题/手改造成的非 dict 条目（如纯字符串）
+                # 会让 open 命令在 item.get 处 AttributeError 崩溃（一个项目都打不开），
+                # 跳过并累计警告
+                valid = [h for h in data if isinstance(h, dict) and h.get("path")]
+                if len(valid) != len(data):
+                    logger.warning(
+                        "忽略 %d 条损坏的历史记录（非对象或缺 path 字段）: %s",
+                        len(data) - len(valid),
+                        HISTORY_FILE,
+                    )
+                return valid
+            return []
+    except json.JSONDecodeError:
+        # JSON 格式损坏，返回空列表
+        return []
+    except PermissionError:
+        # 无权限读取，返回空列表
+        return []
+    except OSError:
+        # 其他操作系统错误（如文件被锁定），返回空列表
+        return []
+
+
+def _save_history(history: list[dict]) -> None:
+    """保存项目打开历史。
+
+    将历史记录写入 HISTORY_FILE。保存失败仅记录日志，不阻断主流程。
+
+    Args:
+        history: 历史记录列表
+    """
+    try:
+        # 确保目录存在（用户主目录）
+        os.makedirs(os.path.dirname(HISTORY_FILE), exist_ok=True)
+        with open(HISTORY_FILE, "w", encoding="utf-8") as f:
+            json.dump(history, f, ensure_ascii=False, indent=2)
+    except (PermissionError, OSError):
+        # 保存失败时记录错误日志，但不阻断主流程
+        logger.error("保存项目历史记录失败", exc_info=True)
+
+
+def add_to_history(project_path: str) -> None:
+    """将项目路径添加到历史记录顶部。
+
+    如果路径已存在，先移除旧记录，再插入到顶部。超过 MAX_HISTORY 时自动截断。
+
+    Args:
+        project_path: 项目的绝对路径
+    """
+    history = load_history()
+    # 去重：移除已存在的相同路径
+    history = [h for h in history if h.get("path") != project_path]
+    # 插入到列表头部（最新的项目），并记录真实打开时间（UTC ISO 格式）。
+    # 历史展示顺序即插入序（最新在前），last_opened 仅供人读/审计，不参与排序。
+    history.insert(0, {"path": project_path, "last_opened": datetime.now(UTC).isoformat()})
+    # 容量控制：只保留最近的 MAX_HISTORY 个项目
+    if len(history) > MAX_HISTORY:
+        history = history[:MAX_HISTORY]
+    _save_history(history)
+
+
+def find_manifest(project_path: str) -> str | None:
+    """定位项目清单文件，兼容 .yaml / .yml 后缀。
+
+    Args:
+        project_path: 项目根目录绝对路径
+
+    Returns:
+        清单文件绝对路径；不存在则返回 None
+    """
+    # 优先 .yaml 后缀（项目规范）
+    primary = os.path.join(project_path, "project.precis.yaml")
+    if os.path.isfile(primary):
+        return primary
+    # 兼容 .yml 后缀
+    alt = os.path.join(project_path, "project.precis.yml")
+    if os.path.isfile(alt):
+        return alt
+    return None
+
+
+def load_manifest_config(manifest_path: str) -> dict | None:
+    """加载并序列化清单为字典。
+
+    复用 shared/core 中的 load_manifest 以保持与系统其余部分解析一致，
+    返回 model_dump() 字典以匹配 project_config 的 dict 消费约定。
+
+    Args:
+        manifest_path: 清单文件绝对路径
+
+    Returns:
+        清单配置字典；解析失败时返回 None（由调用方决定如何提示）
+    """
+    try:
+        # 延迟导入：避免在未使用时引入 shared.core 的依赖链。
+        # 注意 manifest 为 namespace package，需直接从 reader 子模块导入。
+        from app.shared.core.project.manifest.reader import load_manifest
+
+        manifest = load_manifest(manifest_path)
+        return manifest.model_dump(exclude_none=True)
+    except Exception as e:
+        # 记录日志但不抛出，避免加载失败阻断项目切换
+        logger.warning("加载项目清单失败: %s", e, exc_info=True)
+        return None
+
+
+def resolve_project_label(project_path: str) -> str:
+    """解析项目用于菜单显示的名称。
+
+    优先读取 project.precis.yaml 中的 project.name，失败则降级为目录名。
+    用于交互菜单 label，不做完整项目加载。
+
+    Args:
+        project_path: 项目根目录绝对路径
+
+    Returns:
+        项目显示名称
+    """
+    manifest_path = find_manifest(project_path)
+    if manifest_path is not None:
+        config = load_manifest_config(manifest_path)
+        if config is not None:
+            name = config.get("project", {}).get("name")
+            if name:
+                return str(name)
+    # 降级：目录名
+    return os.path.basename(project_path) or project_path
+
+
+@dataclass
+class OpenResult:
+    """打开项目纯逻辑的结果。
+
+    Attributes:
+        success: 是否成功打开
+        project_path: 项目绝对路径
+        config: 清单配置字典（无清单或加载失败时为 None）
+        manifest_path: 清单文件绝对路径；未找到时为 None
+        message: 给用户的消息文案（与原 CLI 文案保持一致，保证零回归）
+    """
+
+    success: bool
+    project_path: str
+    config: dict | None
+    manifest_path: str | None
+    message: str
+
+
+def open_project(project_path: str) -> OpenResult:
+    """打开项目的纯逻辑（存在性校验 + 写历史 + 加载清单）。
+
+    不修改任何 UI 上下文，仅返回 OpenResult 由调用方（CLI/TUI）自行更新各自上下文。
+    消息文案与原 open.py 保持完全一致，确保 CLI 零回归。
+
+    Args:
+        project_path: 项目目录的绝对路径
+
+    Returns:
+        OpenResult：包含成功标志、配置、清单路径与消息文案
+    """
+    if not os.path.exists(project_path):
+        return OpenResult(
+            success=False,
+            project_path=project_path,
+            config=None,
+            manifest_path=None,
+            message=f"项目路径不存在: {project_path}",
+        )
+    if not os.path.isdir(project_path):
+        return OpenResult(
+            success=False,
+            project_path=project_path,
+            config=None,
+            manifest_path=None,
+            message=f"路径不是目录: {project_path}",
+        )
+
+    # 写入历史记录
+    add_to_history(project_path)
+
+    # 定位清单文件，兼容 .yaml / .yml 两种后缀
+    manifest_path = find_manifest(project_path)
+
+    # 加载清单，加载失败不阻断切换项目，仅清空配置并给出警告
+    config: dict | None = None
+    load_warning = ""
+    if manifest_path is not None:
+        loaded = load_manifest_config(manifest_path)
+        if loaded is not None:
+            config = loaded
+        else:
+            config = None
+            load_warning = "\n警告：project.precis.yaml 存在但解析失败，配置未加载"
+
+    msg = f"已切换到项目: {project_path}"
+    if manifest_path is not None:
+        msg += "\n检测到项目清单文件 (project.precis.yaml)"
+    else:
+        msg += "\n警告：未找到 project.precis.yaml，可能需要初始化项目"
+    msg += load_warning
+
+    return OpenResult(
+        success=True,
+        project_path=project_path,
+        config=config,
+        manifest_path=manifest_path,
+        message=msg,
+    )
+
+
+__all__ = [
+    "HISTORY_FILE",
+    "MAX_HISTORY",
+    "OpenResult",
+    "add_to_history",
+    "find_manifest",
+    "load_history",
+    "load_manifest_config",
+    "open_project",
+    "resolve_project_label",
+]

app/cli/shell/__init__.py

@@ -0,0 +1,48 @@
+# 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/__init__.py
+"""
+@fileoverview CLI Shell 模块入口
+
+功能概述:
+- 聚合导出 CLI Shell 核心组件（异常、格式化器）
+- 提供统一的模块外部接口
+"""
+
+from app.cli.shell.exceptions import (
+    CLIError,
+    CommandNotFoundError,
+    ConfigError,
+    EditorError,
+    InvalidProjectError,
+    NoProjectOpenError,
+    ProjectNotFoundError,
+    ValidationError,
+)
+from app.cli.shell.formatter import Colors, Formatter
+
+__all__ = [
+    "CLIError",
+    "ProjectNotFoundError",
+    "InvalidProjectError",
+    "NoProjectOpenError",
+    "CommandNotFoundError",
+    "ValidationError",
+    "ConfigError",
+    "EditorError",
+    "Formatter",
+    "Colors",
+]

app/cli/shell/commands/__init__.py

@@ -0,0 +1,63 @@
+# 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/commands/__init__.py
+"""
+@fileoverview CLI Shell 命令集合入口
+
+功能概述:
+- 聚合导出所有内置 Shell 命令类
+- 统一暴露命令基类与结果类型
+- 作为外部模块导入 commands 包时的统一入口
+
+架构设计:
+- 从各子模块导入具体的命令类
+- 通过 __all__ 显式控制对外暴露的接口
+- 遵循 Python 包导入规范，避免循环依赖
+
+输入示例:
+    from app.cli.shell.commands import HelpCommand, OpenCommand
+
+输出示例:
+    导入后可直接使用 HelpCommand() 等命令类
+"""
+
+from app.cli.shell.commands.ai import AICommand
+from app.cli.shell.commands.base import Command, CommandResult
+from app.cli.shell.commands.config import ConfigCommand
+from app.cli.shell.commands.exit import ExitCommand
+from app.cli.shell.commands.help import HelpCommand
+from app.cli.shell.commands.infer_schema import InferSchemaCommand
+from app.cli.shell.commands.open import OpenCommand
+from app.cli.shell.commands.project import ProjectCommand
+from app.cli.shell.commands.provider import ProviderCommand
+from app.cli.shell.commands.system import LsCommand, PwdCommand
+from app.cli.shell.commands.validate import ValidateCommand
+
+__all__ = [
+    "Command",
+    "CommandResult",
+    "HelpCommand",
+    "OpenCommand",
+    "ProjectCommand",
+    "ValidateCommand",
+    "ConfigCommand",
+    "ExitCommand",
+    "ProviderCommand",
+    "AICommand",
+    "PwdCommand",
+    "LsCommand",
+    "InferSchemaCommand",
+]