precis-cli 0.1.3__py3-none-any.whl

app/cli/shell/commands/exit.py

@@ -0,0 +1,67 @@
+# 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/exit.py
+"""
+@fileoverview CLI Shell 退出命令模块
+
+功能概述:
+- 提供 exit 命令退出交互式 Shell
+- 返回 should_exit=True 的结果使主循环终止
+- 全局快捷键 qq 可直接退出程序
+
+架构设计:
+- ExitCommand 继承 Command 基类
+- execute() 直接返回 CommandResult.exit()，主循环检测 should_exit 后退出
+
+输入示例:
+    precis> exit
+
+输出示例:
+    CommandResult.exit("再见!")
+"""
+
+from app.cli.shell.commands.base import Command, CommandResult, ProjectContext
+
+
+class ExitCommand(Command):
+    """退出命令。
+
+    当用户输入 exit 时触发，使 Shell 主循环终止。
+    全局快捷键 qq 仍可直接退出程序。
+    """
+
+    def __init__(self) -> None:
+        super().__init__("exit")
+
+    @property
+    def description(self) -> str:
+        return "退出 Precis CLI"
+
+    @property
+    def usage(self) -> str:
+        return "exit"
+
+    def execute(self, args: list[str], context: ProjectContext) -> CommandResult:
+        """执行退出命令。
+
+        Args:
+            args: 命令参数列表（此命令不需要参数）
+            context: 项目上下文
+
+        Returns:
+            带有 should_exit=True 的结果，触发 Shell 退出
+        """
+        return CommandResult.exit("再见!")

app/cli/shell/commands/help.py

@@ -0,0 +1,104 @@
+# 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/help.py
+"""
+@fileoverview CLI Shell 帮助命令模块
+
+功能概述:
+- 提供 help 命令显示所有可用命令列表
+- 支持查看特定命令的详细帮助文本
+- 格式化输出命令名称与描述
+
+架构设计:
+- HelpCommand 接收 CommandRegistry 实例，从中获取所有注册命令
+- 无参数时显示所有命令的简要列表
+- 带参数时显示指定命令的详细帮助文本
+
+输入示例:
+    precis> help
+    precis> help validate
+
+输出示例:
+    可用命令列表或特定命令的 help_text
+"""
+
+from rich.console import Console
+from rich.table import Table
+
+from app.cli.shell.commands.base import Command, CommandResult, ProjectContext
+from app.cli.shell.parser import CommandRegistry
+
+_console = Console()
+
+
+class HelpCommand(Command):
+    """帮助命令。
+
+    显示所有可用命令的列表，或查看特定命令的详细帮助。
+    """
+
+    def __init__(self, registry: CommandRegistry):
+        super().__init__("help", aliases=["?"])
+        self._registry = registry
+
+    @property
+    def description(self) -> str:
+        return "显示所有可用命令或特定命令的帮助信息"
+
+    @property
+    def usage(self) -> str:
+        return "help [command]"
+
+    def execute(self, args: list[str], context: ProjectContext) -> CommandResult:
+        if not args:
+            return self._show_all_commands()
+        else:
+            return self._show_command_help(args[0])
+
+    def _show_all_commands(self) -> CommandResult:
+        commands = self._registry.get_all_commands()
+
+        _console.print()
+        _console.print("[bold]可用命令:[/bold]")
+        _console.print()
+
+        table = Table(show_header=False, box=None, padding=(0, 2, 0, 0))
+        table.add_column("Command", style="cyan bold", min_width=18)
+        table.add_column("Description")
+
+        for cmd in commands:
+            # 聚合命令（如 config/project/ai）在描述后追加子命令提示，
+            # 让用户无需先输入命令即可发现 inspect 等子命令的存在。
+            subs = cmd.list_subcommands()
+            if subs:
+                desc = f"{cmd.description}  [dim](子命令: {', '.join(subs)})[/dim]"
+            else:
+                desc = cmd.description
+            table.add_row(cmd.name, desc)
+
+        _console.print(table)
+        _console.print()
+        _console.print("[dim]输入 'help <command>' 查看特定命令的详细帮助[/dim]")
+        _console.print("[dim]输入 'exit' 或 'quit' 退出 CLI，'qq' 强制退出[/dim]")
+
+        return CommandResult.ok("")
+
+    def _show_command_help(self, command_name: str) -> CommandResult:
+        command = self._registry.get(command_name)
+        if command is None:
+            return CommandResult.error(f"未知命令: {command_name}")
+
+        return CommandResult.ok(command.help_text)

app/cli/shell/commands/infer_schema.py

@@ -0,0 +1,156 @@
+# 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/infer_schema.py
+"""
+@fileoverview CLI infer-schema 子命令模块
+
+功能概述:
+- 读取 CSV/Excel/JSON 数据文件头部，推断列类型并输出合法 schema YAML
+- 默认输出到 stdout（管道友好），--output 写入指定文件
+- 推断逻辑在 services 层（app.shared.services.schema_inference），本模块只做参数解析
+
+使用示例:
+    precis infer-schema data/orders.csv
+    precis infer-schema data/orders.csv --output schemas/orders.schema.yaml
+    precis infer-schema data/orders.csv --id <uuid> --name orders --source-path ../orders.csv
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from app.cli.shell.commands.base import Command, CommandResult, ProjectContext
+
+# 选项表：选项名 → 结果键
+_INFER_OPTIONS: dict[str, str] = {
+    "--output": "output",
+    "-o": "output",
+    "--id": "table_id",
+    "--name": "table_name",
+    "--source-path": "source_path",
+    "--sample-rows": "sample_rows",
+}
+
+
+def _parse_infer_args(args: list[str]) -> dict:
+    """解析 infer-schema 参数：选项及值剥离，剩余首个位置参数为数据文件路径。
+
+    Args:
+        args: 命令参数列表
+
+    Returns:
+        包含 data_file/output/table_id/table_name/source_path/sample_rows 的字典
+    """
+    result: dict[str, str | None] = {
+        "data_file": None,
+        "output": None,
+        "table_id": None,
+        "table_name": None,
+        "source_path": None,
+        "sample_rows": None,
+    }
+    positional: list[str] = []
+    i = 0
+    while i < len(args):
+        arg = args[i]
+        key = _INFER_OPTIONS.get(arg)
+        if key and i + 1 < len(args):
+            result[key] = args[i + 1]
+            i += 2
+        elif key:
+            i += 1
+        else:
+            positional.append(arg)
+            i += 1
+    if positional:
+        result["data_file"] = positional[0]
+    return result
+
+
+class InferSchemaCommand(Command):
+    """schema 推断命令：从数据文件头部推断列类型，输出 schema YAML。"""
+
+    def __init__(self) -> None:
+        super().__init__("infer-schema", aliases=["infer"])
+
+    @property
+    def description(self) -> str:
+        return "从数据文件推断 schema（列类型），输出 YAML 草稿"
+
+    @property
+    def usage(self) -> str:
+        return (
+            "infer-schema <数据文件> [--output <path>] [--id <uuid>] [--name <表名>] "
+            "[--source-path <数据相对路径>] [--sample-rows <N>]"
+        )
+
+    def execute(self, args: list[str], context: ProjectContext) -> CommandResult:
+        """执行 schema 推断。
+
+        Args:
+            args: 命令参数（数据文件路径 + 选项）
+            context: 命令上下文（本命令不依赖项目状态）
+
+        Returns:
+            成功时 data 携带推断结果字典；参数/文件错误返回 exit_code=2
+        """
+        parsed = _parse_infer_args(args)
+        data_file = parsed["data_file"]
+
+        if not data_file:
+            return CommandResult.error("缺少数据文件路径参数", exit_code=2)
+
+        sample_rows: int = 1000
+        if parsed["sample_rows"] is not None:
+            try:
+                sample_rows = int(parsed["sample_rows"])  # type: ignore[arg-type]
+                if sample_rows <= 0:
+                    raise ValueError
+            except ValueError:
+                return CommandResult.error(f"--sample-rows 必须为正整数: {parsed['sample_rows']}", exit_code=2)
+
+        from app.shared.services.schema_inference import infer_schema
+
+        try:
+            schema = infer_schema(
+                data_file,
+                sample_rows=sample_rows,
+                table_id=parsed["table_id"],
+                table_name=parsed["table_name"],
+                source_path=parsed["source_path"],
+            )
+        except ValueError as e:
+            return CommandResult.error(str(e), exit_code=2)
+
+        yaml_text = yaml.safe_dump(schema, allow_unicode=True, sort_keys=False)
+
+        if parsed["output"]:
+            output_path = Path(parsed["output"])
+            try:
+                # 父目录不存在时创建，方便直接写入 <proj>/schemas/ 子路径
+                output_path.parent.mkdir(parents=True, exist_ok=True)
+                output_path.write_text(yaml_text, encoding="utf-8")
+            except OSError as e:
+                return CommandResult.error(f"写入输出文件失败: {e}", exit_code=2)
+            return CommandResult.ok(
+                f"schema 已写入: {output_path}", data={"schema": schema, "output": str(output_path)}
+            )
+
+        # stdout 输出纯 YAML（无 rich 装饰，管道/重定向友好）
+        print(yaml_text, end="")
+        return CommandResult.ok("", data={"schema": schema})

app/cli/shell/commands/open.py

@@ -0,0 +1,201 @@
+# 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/open.py
+"""
+@fileoverview CLI Shell 打开项目命令模块
+
+功能概述:
+- 提供 open 命令：打开并切换工作项目，维护项目历史记录
+- 管理项目打开历史（持久化到 ~/.precis_project_history）
+
+架构设计:
+- OpenCommand 作为顶层命令注册，同时被 ProjectCommand 复用为子命令
+- 历史记录与项目打开的纯逻辑委托给 shared_services.project_ops（CLI/TUI 同源）
+- 本模块只保留交互部分（InteractiveMenu 历史选择）与命令编排
+- 错误处理通过 CommandResult.error 直接返回，不抛出异常
+
+输入示例:
+    open /path/to/project
+    project open /path/to/project
+
+输出示例:
+    CommandResult(success=True, message="已切换到项目: /path/to/project")
+"""
+
+import os
+
+from app.cli.shared_services import project_ops
+from app.cli.shell.commands.base import Command, CommandResult, ProjectContext
+
+# 向后兼容 re-export：历史代码与集成测试通过 open 模块访问历史函数与常量。
+# 真正的实现已迁移到 shared_services.project_ops（CLI/TUI 同源）。
+HISTORY_FILE = project_ops.HISTORY_FILE
+MAX_HISTORY = project_ops.MAX_HISTORY
+_load_history = project_ops.load_history
+_save_history = project_ops._save_history
+_add_to_history = project_ops.add_to_history
+
+
+class OpenCommand(Command):
+    """打开项目命令。
+
+    支持三种调用方式：
+        open               → 从历史记录交互选择（箭头/数字键，Enter=最近项目）
+        open <N>           → 打开历史列表第 N 个项目（1-based）
+        open <项目路径>     → 按路径打开项目
+
+    打开成功后更新上下文（project_path/project_config）并写入历史记录。
+    """
+
+    def __init__(self) -> None:
+        super().__init__("open", aliases=["o"])
+
+    @property
+    def description(self) -> str:
+        return "打开一个项目目录并切换当前上下文（无参数从历史选择）"
+
+    @property
+    def usage(self) -> str:
+        return "open [项目路径 | 序号]（无参数则从历史选择）"
+
+    def execute(self, args: list[str], ctx: ProjectContext) -> CommandResult:
+        """执行打开项目命令。
+
+        支持三种调用方式：
+            open                 → 方案A：无参数，从历史记录交互选择
+            open <N>             → 方案B：打开历史列表第 N 个项目（1-based）
+            open <项目路径>       → 按路径打开项目
+
+        Args:
+            args: 命令参数列表
+            ctx: 项目上下文，用于保存当前项目路径
+
+        Returns:
+            命令执行结果
+        """
+        # 方案A：无参数 → 交互式从历史选择
+        if not args:
+            return self._open_from_history(ctx)
+
+        # 方案B：纯数字参数 → 按历史序号打开（拦截在路径解析之前，
+        # 避免 "1" 被当成名为 "1" 的路径；真有同名目录可用 open ./1 绕过）
+        if args[0].isdigit():
+            return self._open_by_index(args[0], ctx)
+
+        # 默认：按路径打开
+        return self._do_open_path(os.path.abspath(args[0]), ctx)
+
+    def _do_open_path(self, project_path: str, ctx: ProjectContext) -> CommandResult:
+        """按绝对路径打开项目的公共逻辑（供方案A/B/路径模式复用）。
+
+        委托 shared_services.project_ops.open_project 执行纯逻辑（存在性校验 +
+        写历史 + 加载清单），再更新 CLI 上下文。
+
+        Args:
+            project_path: 项目目录的绝对路径
+            ctx: 命令上下文
+
+        Returns:
+            命令执行结果
+        """
+        result = project_ops.open_project(project_path)
+        if result.success:
+            # 更新上下文中的项目路径与配置
+            ctx.project_path = result.project_path
+            ctx.project_config = result.config
+        return CommandResult(success=result.success, message=result.message)
+
+    def _open_from_history(self, ctx: ProjectContext) -> CommandResult:
+        """方案A：无参数时从历史记录交互选择项目。
+
+        使用 InteractiveMenu 渲染历史项目列表（光标默认停在最近项目，
+        直接 Enter 即可打开上次项目）。空历史或取消时返回提示，不报错。
+
+        Args:
+            ctx: 命令上下文
+
+        Returns:
+            命令执行结果
+        """
+        # 延迟导入：InteractiveMenu 依赖 readchar，仅在交互分支才需要
+        from app.cli.shell.interactive_menu import InteractiveMenu
+
+        history = project_ops.load_history()
+        if not history:
+            return CommandResult(
+                success=True,
+                message="暂无项目打开历史。请先使用 'open <项目路径>' 打开一个项目。",
+            )
+
+        # 构建菜单项：key=项目路径，label=项目名（优先 manifest，否则目录名），description=完整路径
+        menu = InteractiveMenu("从历史记录中选择项目:", show_cancel=True)
+        for item in history:
+            path = item.get("path", "")
+            if not path:
+                continue
+            label = project_ops.resolve_project_label(path)
+            menu.add_item(key=path, label=label, description=path)
+
+        if not menu.items:
+            return CommandResult(
+                success=True,
+                message="历史记录中无有效项目路径。请使用 'open <项目路径>' 打开项目。",
+            )
+
+        selected_path = menu.show()
+        if selected_path is None:
+            # 用户取消（ESC / 0 / 选了取消项）
+            return CommandResult(success=True, message="已取消。")
+
+        return self._do_open_path(selected_path, ctx)
+
+    def _open_by_index(self, index_str: str, ctx: ProjectContext) -> CommandResult:
+        """方案B：按历史序号打开项目（1-based）。
+
+        Args:
+            index_str: 用户输入的纯数字字符串
+            ctx: 命令上下文
+
+        Returns:
+            命令执行结果
+        """
+        history = project_ops.load_history()
+        if not history:
+            return CommandResult(
+                success=False,
+                message="暂无项目打开历史，无法按序号打开。请使用 'open <项目路径>' 打开项目。",
+            )
+
+        # 解析序号（已在 execute 中确认 isdigit()，此处再防御一次）
+        try:
+            index = int(index_str)
+        except ValueError:
+            return CommandResult(success=False, message=f"无效的序号: {index_str}")
+
+        if index < 1 or index > len(history):
+            return CommandResult(
+                success=False,
+                message=f"无此历史项: {index}（共 {len(history)} 项，使用 'project history' 查看列表）",
+            )
+
+        path = history[index - 1].get("path", "")
+        if not path:
+            return CommandResult(success=False, message=f"历史项 {index} 缺少路径信息")
+
+        return self._do_open_path(path, ctx)
+
+
+__all__ = ["OpenCommand"]