precis-cli 0.1.3__py3-none-any.whl

app/api/routers/project/view.py

@@ -0,0 +1,177 @@
+# 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 项目视图 API - 画布布局管理
+
+功能概述:
+- 提供前端画布视图（节点位置、视口信息）的读写接口
+- 视图文件与 manifest 分离，避免 UI 状态污染配置语义
+- 文件不存在时返回默认空视图，保证前端始终能获取有效数据
+
+架构设计:
+- 使用 JSON 格式存储，便于前端快速序列化/反序列化
+- 读取时兜底返回默认视图，写入时直接覆盖
+- 通过 _v2_view_path 统一计算视图文件路径
+
+输入示例:
+    GET /view
+    PUT /view (body: ProjectViewV2Model)
+
+输出示例:
+    ProjectViewV2Model: {version, nodes, viewport}
+    StandardResponse: 操作结果消息
+"""
+
+import json
+import logging
+import os
+import tempfile
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from app.api.dependencies import get_project_config_path
+from app.api.services.io_error_messages import describe_io_error
+
+from .base import (
+    ProjectViewV2Model,
+    StandardResponse,
+    _v2_view_path,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="", tags=["Project-View"])
+
+
+def _write_json_atomic(path: str, data: dict) -> None:
+    """原子写入 JSON 文件（临时文件 + os.replace）。
+
+    view.json 属于高频覆写文件，此前用裸 open("w") 直写：进程在写入中途崩溃/断电
+    会留下半个 JSON，下次读取直接 500。参照 write_yaml_atomic 的思路：先写同目录
+    临时文件并 fsync，再用 os.replace 原子替换（POSIX 与 Windows 均保证同一文件
+    系统内替换的原子性）；任一步失败时清理临时文件后原样抛出。
+
+    参数:
+        path: 目标 JSON 文件路径
+        data: 待序列化的字典
+    """
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    fd, temp_path = tempfile.mkstemp(dir=target.parent, suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(data, f, ensure_ascii=False, indent=2)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(temp_path, target)
+    except Exception:
+        # 失败时尽力清理临时文件，避免 .precis/ 目录残留 *.tmp 垃圾
+        if os.path.exists(temp_path):
+            try:
+                os.remove(temp_path)
+            except OSError:
+                pass
+        raise
+
+
+@router.get(
+    "/view",
+    response_model=ProjectViewV2Model,
+    summary="获取项目画布视图",
+    responses={
+        500: {"description": "服务器内部错误"},
+    },
+)
+def get_v2_project_view(config_path: str = Depends(get_project_config_path)) -> ProjectViewV2Model:
+    """
+    获取 V2 项目视图文件（画布布局）。
+
+    使用场景：
+    - 前端加载项目时恢复画布节点位置
+    - 用户打开已保存的项目时恢复之前的查看位置
+
+    副作用：
+    - 如果视图文件不存在，返回默认空视图而非 404，保证前端总能拿到有效数据
+
+    数据流：
+    1. 尝试从文件系统读取 project.view.json
+    2. 如果文件不存在，返回默认视图 {version: 1, nodes: {}, viewport: null}
+    3. 如果读取失败（如 JSON 解析错误），返回 500 错误
+
+    参数:
+        config_path: 项目配置根目录（通过 Depends 注入）
+
+    返回:
+        ProjectViewV2Model: 包含节点位置和视口信息
+    """
+    view_path = _v2_view_path(config_path)
+    if not os.path.isfile(view_path):
+        return ProjectViewV2Model(version=1, nodes={})
+
+    try:
+        with open(view_path, encoding="utf-8") as f:
+            data = json.load(f) or {}
+        return ProjectViewV2Model(**data)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"读取视图文件失败：{describe_io_error(e)}")
+
+
+@router.put(
+    "/view",
+    response_model=StandardResponse,
+    summary="更新项目画布视图",
+    responses={
+        400: {"description": "请求参数错误"},
+        500: {"description": "服务器内部错误"},
+    },
+)
+def put_v2_project_view(
+    payload: ProjectViewV2Model,
+    config_path: str = Depends(get_project_config_path),
+) -> StandardResponse:
+    """
+    更新 V2 项目视图文件（画布布局）。
+
+    使用场景：
+    - 用户拖拽节点后保存位置
+    - 用户缩放/平移画布后保存视口
+    - 定期自动保存画布状态
+
+    副作用：
+    - 直接覆盖写入视图文件
+    - 使用 ensure_ascii=False 支持中文节点名称
+
+    数据流：
+    1. 接收前端传来的视图数据（节点坐标 + 视口）
+    2. 转换为 JSON 格式写入文件
+    3. 返回成功消息
+
+    参数:
+        payload: 前端传来的视图数据
+        config_path: 项目配置根目录（通过 Depends 注入）
+
+    返回:
+        StandardResponse: 操作结果消息
+    """
+    view_path = _v2_view_path(config_path)
+    try:
+        # B-reliability: 原子写替代裸 open("w")，进程中断不再留下半个 JSON
+        _write_json_atomic(view_path, payload.model_dump())
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"写入视图文件失败：{describe_io_error(e)}")
+
+    return StandardResponse(message="Project view saved")

app/api/routers/project/workspaces.py

@@ -0,0 +1,167 @@
+# 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 项目工作区 API - 多标签页画布状态持久化
+
+功能概述:
+- 提供前端多工作区（multi-tab canvas）的读写接口
+- 工作区只存储视图差异（可见节点、视口），不存储完整项目配置
+- 项目配置仍由 V2 YAML 体系（manifest/schema/constraint/regex）承载
+
+架构设计:
+- 与 project.view.json 分工协作：view.json 存节点坐标，workspaces.json 存工作区列表
+- 文件不存在时返回默认空配置，保证前端始终能获取有效数据
+- 使用 JSON 格式，便于前端快速序列化/反序列化
+
+输入示例:
+    GET /workspaces
+    PUT /workspaces (body: WorkspacesV2Model)
+
+输出示例:
+    WorkspacesV2Model: {version, activeWorkspaceId, workspaces}
+    StandardResponse: 操作结果消息
+"""
+
+import json
+import logging
+import os
+import tempfile
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from app.api.dependencies import get_project_config_path
+from app.api.services.io_error_messages import describe_io_error
+
+from .base import (
+    StandardResponse,
+    WorkspacesV2Model,
+    _v2_workspaces_path,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="", tags=["Project-Workspaces"])
+
+
+def _write_json_atomic(path: str, data: dict) -> None:
+    """原子写入 JSON 文件（临时文件 + os.replace）。
+
+    workspaces.json 属于高频覆写文件，此前用裸 open("w") 直写：进程在写入中途
+    崩溃/断电会留下半个 JSON，下次读取直接 500。参照 write_yaml_atomic 的思路：
+    先写同目录临时文件并 fsync，再用 os.replace 原子替换（POSIX 与 Windows 均保证
+    同一文件系统内替换的原子性）；任一步失败时清理临时文件后原样抛出。
+
+    参数:
+        path: 目标 JSON 文件路径
+        data: 待序列化的字典
+    """
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    fd, temp_path = tempfile.mkstemp(dir=target.parent, suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(data, f, ensure_ascii=False, indent=2)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(temp_path, target)
+    except Exception:
+        # 失败时尽力清理临时文件，避免 .precis/ 目录残留 *.tmp 垃圾
+        if os.path.exists(temp_path):
+            try:
+                os.remove(temp_path)
+            except OSError:
+                pass
+        raise
+
+
+@router.get(
+    "/workspaces",
+    response_model=WorkspacesV2Model,
+    summary="获取 V2 项目工作区配置",
+    responses={
+        500: {"description": "读取工作区文件失败"},
+    },
+)
+def get_v2_workspaces(config_path: str = Depends(get_project_config_path)) -> WorkspacesV2Model:
+    """
+    获取 V2 项目工作区配置。
+
+    使用场景：
+    - 前端加载项目时恢复多标签页工作区状态
+    - 用户刷新页面后恢复之前的工作区列表和活跃标签
+
+    副作用：
+    - 如果工作区文件不存在，返回默认空配置而非 404，保证前端总能拿到有效数据
+
+    参数:
+        config_path: 项目配置根目录（通过 Depends 注入）
+
+    返回:
+        WorkspacesV2Model: 包含工作区列表和当前活跃工作区 ID
+    """
+    workspaces_path = _v2_workspaces_path(config_path)
+    if not os.path.isfile(workspaces_path):
+        return WorkspacesV2Model(version=1, activeWorkspaceId=None, workspaces=[])
+
+    try:
+        with open(workspaces_path, encoding="utf-8") as f:
+            data = json.load(f) or {}
+        return WorkspacesV2Model(**data)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"读取工作区文件失败：{describe_io_error(e)}")
+
+
+@router.put(
+    "/workspaces",
+    response_model=StandardResponse,
+    summary="更新 V2 项目工作区配置",
+    responses={
+        500: {"description": "写入工作区文件失败"},
+    },
+)
+def put_v2_workspaces(
+    payload: WorkspacesV2Model,
+    config_path: str = Depends(get_project_config_path),
+) -> StandardResponse:
+    """
+    更新 V2 项目工作区配置。
+
+    使用场景：
+    - 用户创建/重命名/关闭工作区标签页时保存状态
+    - 用户切换活跃工作区时保存当前选择
+    - 用户拖拽排序工作区时保存新顺序
+
+    副作用：
+    - 自动创建 .precis 目录（如果不存在）
+    - 直接覆盖写入工作区文件
+    - 使用 ensure_ascii=False 支持中文工作区名称
+
+    参数:
+        payload: 前端传来的工作区数据
+        config_path: 项目配置根目录（通过 Depends 注入）
+
+    返回:
+        StandardResponse: 操作结果消息
+    """
+    workspaces_path = _v2_workspaces_path(config_path)
+    try:
+        # B-reliability: 原子写替代裸 open("w")，进程中断不再留下半个 JSON
+        _write_json_atomic(workspaces_path, payload.model_dump())
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"写入工作区文件失败：{describe_io_error(e)}")
+
+    return StandardResponse(message="Workspaces saved")

app/api/routers/projects/__init__.py

@@ -0,0 +1,25 @@
+# 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.
+"""项目管理路由聚合：/api/latest/projects 下的扫描、打开、创建子路由。"""
+
+from fastapi import APIRouter
+
+from . import create, open, scan
+
+router = APIRouter(prefix="/api/latest/projects", tags=["Projects"])
+router.include_router(scan.router)
+router.include_router(open.router)
+router.include_router(create.router)

app/api/routers/projects/create.py

@@ -0,0 +1,121 @@
+# 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 Web 端新建项目 API
+
+功能概述:
+- 创建一个新的 Precis 项目脚手架
+- 生成标准目录结构与最小 manifest
+- 设置为"当前项目"
+
+架构设计:
+- 与 open.py 对称：create 写入脚手架，open 验证并加载
+- Web 模式下文件系统可见，直接在请求路径下创建
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+from fastapi import APIRouter, HTTPException, Request
+
+from app.api.models.projects import CreateProjectRequest, CreateProjectResponse
+from app.shared.core.io.yaml import write_yaml_atomic
+
+router = APIRouter(prefix="", tags=["Projects-Create"])
+
+# 标准项目子目录
+_REQUIRED_SUBDIRS = [
+    "schemas",
+    "constraints",
+    "regex_nodes",
+    "transforms",
+    "patterns",
+    "templates",
+    "data",
+    ".precis",
+]
+
+
+# 最小空项目 manifest 模板（与 qa_simple 结构对齐）
+def _build_min_manifest(project_name: str) -> dict:
+    """根据项目名构造最小可用 manifest。"""
+    # id 由项目名派生：小写 + 仅保留字母数字与下划线
+    raw_id = re.sub(r"[^a-zA-Z0-9_]", "_", project_name.strip().lower()) or "project"
+    return {
+        "version": 2,
+        "project": {"id": raw_id, "name": project_name},
+        "settings": {
+            "validation": {
+                "auto_validate": False,
+                "strict_mode": False,
+                "error_handling": "continue",
+                "timeout_seconds": 30,
+            },
+            "file_processing": {"default_encoding": "utf-8"},
+            "script_security": {"allow_eval": False, "allow_exec": False},
+        },
+        "schemas": [],
+        "constraints": [],
+        "regex_nodes": [],
+        "transforms": [],
+        "data_sources": [],
+        "templates": [],
+        "template_instances": [],
+        "patterns_dir": "patterns",
+        "warnings": [],
+    }
+
+
+@router.post(
+    "/create",
+    response_model=CreateProjectResponse,
+    summary="创建一个新的 Precis 项目脚手架",
+)
+def create_project(
+    request: CreateProjectRequest,
+    http_request: Request,
+) -> CreateProjectResponse:
+    """创建项目目录、写入最小 manifest 与标准子目录，并将其设为当前项目。"""
+    name = request.name.strip()
+    if not name:
+        raise HTTPException(status_code=400, detail="项目名称不能为空")
+
+    project_path = os.path.abspath(os.path.normpath(request.path))
+    manifest_path = os.path.join(project_path, "project.precis.yaml")
+
+    # 若已是合法项目（manifest 存在），拒绝覆盖
+    if os.path.isfile(manifest_path):
+        raise HTTPException(
+            status_code=400,
+            detail=f"目录已是 Precis 项目（存在 manifest）: {project_path}",
+        )
+
+    # 创建目录与标准子目录
+    os.makedirs(project_path, exist_ok=True)
+    for sub in _REQUIRED_SUBDIRS:
+        os.makedirs(os.path.join(project_path, sub), exist_ok=True)
+
+    # 写入最小 manifest
+    write_yaml_atomic(Path(manifest_path), _build_min_manifest(name))
+
+    # 设为当前项目（与 open 行为一致）
+    http_request.app.state.current_project_path = project_path
+    http_request.app.state.current_project_name = name
+
+    return CreateProjectResponse(success=True, name=name, path=project_path)

app/api/routers/projects/open.py

@@ -0,0 +1,103 @@
+# 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.
+"""项目打开路由：打开、关闭与查询当前项目。"""
+
+from __future__ import annotations
+
+import os
+
+import yaml
+from fastapi import APIRouter, HTTPException, Request
+
+from app.api.models.projects import (
+    CloseProjectResponse,
+    CurrentProjectResponse,
+    OpenProjectRequest,
+    OpenProjectResponse,
+)
+
+router = APIRouter(prefix="", tags=["Projects-Open"])
+
+
+def _get_project_name(project_path: str) -> str:
+    """从 project.precis.yaml 中读取项目名称，失败时返回目录名。"""
+    manifest_path = os.path.join(project_path, "project.precis.yaml")
+    try:
+        with open(manifest_path, encoding="utf-8") as f:
+            manifest = yaml.safe_load(f)
+        if isinstance(manifest, dict):
+            project = manifest.get("project", {})
+            if isinstance(project, dict):
+                name = project.get("name")
+                if name:
+                    return str(name)
+    except Exception:
+        pass
+    return os.path.basename(project_path)
+
+
+@router.post(
+    "/open",
+    response_model=OpenProjectResponse,
+    summary="打开一个 Precis 项目",
+)
+def open_project(
+    request: OpenProjectRequest,
+    http_request: Request,
+) -> OpenProjectResponse:
+    """打开指定路径的项目，将其设置为"当前项目"。"""
+    project_path = os.path.abspath(os.path.normpath(request.path))
+    if not os.path.isdir(project_path):
+        raise HTTPException(status_code=404, detail=f"项目目录不存在: {project_path}")
+
+    manifest_path = os.path.join(project_path, "project.precis.yaml")
+    if not os.path.isfile(manifest_path):
+        raise HTTPException(
+            status_code=400,
+            detail=f"目录不是有效的 Precis 项目（缺少 project.precis.yaml）: {project_path}",
+        )
+
+    name = _get_project_name(project_path)
+    http_request.app.state.current_project_path = project_path
+    http_request.app.state.current_project_name = name
+
+    return OpenProjectResponse(success=True, name=name, path=project_path)
+
+
+@router.get(
+    "/current",
+    response_model=CurrentProjectResponse,
+    summary="获取当前打开的项目信息",
+)
+def get_current_project(http_request: Request) -> CurrentProjectResponse:
+    """返回当前打开的项目路径和名称。"""
+    path = getattr(http_request.app.state, "current_project_path", None)
+    if not path:
+        return CurrentProjectResponse(has_current=False)
+    name = getattr(http_request.app.state, "current_project_name", None) or os.path.basename(path)
+    return CurrentProjectResponse(has_current=True, path=path, name=name)
+
+
+@router.post(
+    "/close",
+    response_model=CloseProjectResponse,
+    summary="关闭当前项目",
+)
+def close_project(http_request: Request) -> CloseProjectResponse:
+    """关闭当前项目，清除状态。"""
+    http_request.app.state.current_project_path = None
+    http_request.app.state.current_project_name = None
+    return CloseProjectResponse(success=True)

app/api/routers/projects/scan.py

@@ -0,0 +1,100 @@
+# 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.
+"""项目扫描路由：扫描工作目录下所有包含 project.precis.yaml 的项目。"""
+
+from __future__ import annotations
+
+import os
+from datetime import datetime
+
+import yaml
+from fastapi import APIRouter, HTTPException, Query
+
+from app.api.models.projects import ProjectInfo, ScanResponse
+
+router = APIRouter(prefix="", tags=["Projects-Scan"])
+
+
+@router.get(
+    "/scan",
+    response_model=ScanResponse,
+    summary="扫描工作目录下的所有 Precis 项目",
+)
+def scan_projects(
+    work_dir: str | None = Query(None, description="要扫描的工作目录绝对路径"),
+) -> ScanResponse:
+    """扫描指定工作目录，找出所有包含 project.precis.yaml 的子目录。"""
+    if not work_dir:
+        work_dir = os.environ.get("PRECIS_WORK_DIR")
+    if not work_dir:
+        raise HTTPException(
+            status_code=400,
+            detail="请指定 work_dir 参数或设置 PRECIS_WORK_DIR 环境变量",
+        )
+
+    if not os.path.isdir(work_dir):
+        raise HTTPException(status_code=400, detail=f"工作目录不存在: {work_dir}")
+
+    projects: list[ProjectInfo] = []
+    try:
+        for entry in os.scandir(work_dir):
+            if not entry.is_dir():
+                continue
+            manifest_path = os.path.join(entry.path, "project.precis.yaml")
+            if not os.path.isfile(manifest_path):
+                continue
+            info = _parse_project(entry.path, manifest_path)
+            if info:
+                projects.append(info)
+    except PermissionError as e:
+        raise HTTPException(status_code=403, detail=f"无权限访问目录: {e}")
+
+    projects.sort(key=lambda p: p.last_modified, reverse=True)
+    return ScanResponse(work_dir=os.path.abspath(work_dir), projects=projects)
+
+
+def _parse_project(project_path: str, manifest_path: str) -> ProjectInfo | None:
+    """解析单个项目的 manifest 文件获取元信息。"""
+    try:
+        with open(manifest_path, encoding="utf-8") as f:
+            manifest = yaml.safe_load(f)
+    except Exception:
+        return None
+
+    if not isinstance(manifest, dict):
+        return None
+
+    project = manifest.get("project", {})
+    if not isinstance(project, dict):
+        return None
+
+    name = project.get("name", os.path.basename(project_path))
+    schemas = manifest.get("schemas", []) or []
+    constraints = manifest.get("constraints", []) or []
+
+    try:
+        mtime = os.path.getmtime(manifest_path)
+        last_modified = datetime.fromtimestamp(mtime).isoformat()
+    except OSError:
+        last_modified = ""
+
+    return ProjectInfo(
+        name=str(name),
+        path=os.path.abspath(project_path),
+        schema_count=len(schemas) if isinstance(schemas, list) else 0,
+        constraint_count=len(constraints) if isinstance(constraints, list) else 0,
+        last_modified=last_modified,
+    )