web-presentation-cli 0.1.0__py3-none-any.whl

wp/commands/common.py

@@ -0,0 +1,182 @@
+"""文件功能：提供 CLI 命令共享的客户端、文件载荷、异步任务和输出辅助函数。"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, NoReturn
+
+import click
+
+from wp.client import ApiClient, ApiClientError
+from wp.config import get_profile, load_config
+from wp.formatter import print_error, print_json
+
+
+def get_client(ctx: click.Context) -> ApiClient:
+    """根据当前命令上下文创建绑定 Profile 和 Workspace 的 API Client。"""
+
+    profile = get_profile(load_config(), ctx.obj.get("profile"))
+    return ApiClient(
+        profile,
+        workspace_id=ctx.obj.get("workspace_id"),
+        idempotency_key=ctx.obj.get("idempotency_key"),
+    )
+
+
+def _validate_idempotency_key(
+    ctx: click.Context,
+    _: click.Parameter,
+    value: str | None,
+) -> str | None:
+    """校验并保存命令级幂等键，供当前命令创建的 API Client 使用。"""
+
+    if value is None:
+        return None
+    normalized = value.strip()
+    if not normalized:
+        raise click.BadParameter("幂等键不能为空。")
+    if len(normalized) > 128 or not normalized.isascii():
+        raise click.BadParameter("幂等键必须是不超过 128 个字符的 ASCII 字符串。")
+    ctx.ensure_object(dict)
+    ctx.obj["idempotency_key"] = normalized
+    return normalized
+
+
+def idempotency_key_option(command: Any) -> Any:
+    """为写命令增加可复用的 `--idempotency-key` 选项。"""
+
+    return click.option(
+        "--idempotency-key",
+        callback=_validate_idempotency_key,
+        expose_value=False,
+        metavar="KEY",
+        help="写操作幂等键；请求超时后可用同一键安全重放。",
+    )(command)
+
+
+def read_json_file(file_path: str, *, label: str = "JSON 文件") -> Any:
+    """读取 UTF-8 JSON 文件，并把文件错误转换为 Click 参数错误。"""
+
+    try:
+        content = Path(file_path).read_text(encoding="utf-8")
+        return json.loads(content)
+    except (OSError, UnicodeDecodeError) as exc:
+        raise click.ClickException(f"无法读取{label} '{file_path}': {exc}") from exc
+    except json.JSONDecodeError as exc:
+        raise click.ClickException(f"{label} '{file_path}' 不是合法 JSON: {exc}") from exc
+
+
+def read_text_file(file_path: str, *, label: str = "文本文件") -> str:
+    """读取 UTF-8 文本文件，保留原始内容。"""
+
+    try:
+        return Path(file_path).read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        raise click.ClickException(f"无法读取{label} '{file_path}': {exc}") from exc
+
+
+def require_object(value: Any, *, label: str) -> dict[str, Any]:
+    """校验载荷根节点必须为 JSON 对象。"""
+
+    if not isinstance(value, dict):
+        raise click.ClickException(f"{label}必须是 JSON 对象。")
+    return value
+
+
+def require_array(value: Any, *, label: str) -> list[Any]:
+    """校验载荷根节点必须为 JSON 数组。"""
+
+    if not isinstance(value, list):
+        raise click.ClickException(f"{label}必须是 JSON 数组。")
+    return value
+
+
+def require_ids(value: Any, *, label: str = "ID 列表") -> list[int]:
+    """校验批量归档文件是只包含正整数 ID 的 JSON 数组。"""
+
+    items = require_array(value, label=label)
+    if any(isinstance(item, bool) or not isinstance(item, int) or item < 1 for item in items):
+        raise click.ClickException(f"{label}必须是只包含正整数的 JSON 数组。")
+    return items
+
+
+def output_result(ctx: click.Context, value: Any) -> None:
+    """输出命令结果；复杂响应统一使用 JSON，保证 CLI 与 Agent 消费一致。"""
+
+    print_json(value)
+
+
+def handle_api_error(message: str, error: ApiClientError) -> NoReturn:
+    """统一打印结构化 API 错误并以非零状态退出。"""
+
+    print_error(
+        f"{message}: {error.message}",
+        code=error.code,
+        details=error.details,
+        request_id=error.request_id,
+        retry_after=error.retry_after,
+    )
+    raise SystemExit(1)
+
+
+def resolve_wait_job(
+    client: ApiClient,
+    job: dict[str, Any],
+    *,
+    wait: bool,
+    timeout: float,
+) -> dict[str, Any]:
+    """按命令的 wait 选择返回入队结果或任务终态。"""
+
+    if not wait:
+        return job
+    job_id = str(job.get("job_id") or "")
+    if not job_id:
+        raise click.ClickException("服务端未返回 job_id，无法等待异步任务。")
+    return client.poll_mutation_job(job_id, timeout_seconds=timeout)
+
+
+def require_success_job(job: dict[str, Any], *, ctx: click.Context | None = None) -> dict[str, Any]:
+    """将失败或取消的任务转换为 CLI 失败退出。"""
+
+    if job.get("status") in {"failed", "canceled"}:
+        raw_error = job.get("error") or {}
+        error = raw_error if isinstance(raw_error, dict) else {"message": str(raw_error)}
+        if ctx is not None:
+            if ctx.obj.get("as_json"):
+                print_json(job)
+            else:
+                print_error(
+                    f"异步任务执行失败: {error.get('message') or '未提供错误信息。'}",
+                    code=error.get("code"),
+                    details=error,
+                )
+            raise SystemExit(1)
+        raise click.ClickException(str(error.get("message") or "异步任务执行失败。"))
+    return job
+
+
+def confirm_archive(ids: list[int], *, yes: bool, label: str) -> None:
+    """对单项或批量归档执行统一确认。"""
+
+    if yes:
+        return
+    if not click.confirm(f"确定要归档 {label} {', '.join(map(str, ids))} 吗？"):
+        raise click.Abort()
+
+
+__all__ = [
+    "confirm_archive",
+    "get_client",
+    "handle_api_error",
+    "idempotency_key_option",
+    "output_result",
+    "read_json_file",
+    "read_text_file",
+    "require_array",
+    "require_ids",
+    "require_object",
+    "require_success_job",
+    "resolve_wait_job",
+]

wp/commands/component.py

@@ -0,0 +1,293 @@
+"""文件功能：提供工作空间组件的查询、创建、编辑、校验、发布与归档命令。"""
+
+from __future__ import annotations
+
+import click
+
+from wp.client import ApiClientError
+from wp.commands.common import (
+    confirm_archive,
+    get_client,
+    handle_api_error,
+    idempotency_key_option,
+    output_result,
+    read_json_file,
+    read_text_file,
+    require_array,
+    require_ids,
+    require_object,
+    require_success_job,
+    resolve_wait_job,
+)
+from wp.config import get_profile, load_config
+from wp.formatter import print_table
+
+
+@click.group("component")
+def component_group() -> None:
+    """工作空间组件管理与 Mutation 任务。"""
+
+
+@component_group.command("list")
+@click.option("--page", default=1, type=int)
+@click.option("--page-size", default=50, type=int)
+@click.option("--keyword")
+@click.option("--scope", type=click.Choice(["all", "suggested"]), default="all")
+@click.option("--project-id", type=int)
+@click.pass_context
+def list_components_cmd(ctx: click.Context, page: int, page_size: int, keyword: str | None, scope: str, project_id: int | None) -> None:
+    """查询工作空间组件或项目建议组件。"""
+
+    if scope == "suggested" and project_id is None:
+        raise click.UsageError("scope=suggested 时必须提供 --project-id。")
+    params = {"page": page, "page_size": page_size, "keyword": keyword, "scope": scope, "project_id": project_id}
+    try:
+        result = get_client(ctx).get("/components", params={key: value for key, value in params.items() if value is not None})
+        if ctx.obj.get("as_json"):
+            output_result(ctx, result)
+            return
+        rows = [
+            [item.get("id"), item.get("import_name", "-"), item.get("name", "-"), item.get("component_type", "-"), item.get("status", "-")]
+            for item in result.get("items", [])
+        ]
+        print_table("组件列表", ["ID", "导入标识", "名称", "类型", "状态"], rows)
+    except ApiClientError as err:
+        handle_api_error("获取组件列表失败", err)
+
+
+@component_group.command("get")
+@click.argument("component_id", type=int)
+@click.pass_context
+def get_component_cmd(ctx: click.Context, component_id: int) -> None:
+    """获取组件详情。"""
+
+    try:
+        output_result(ctx, get_client(ctx).get(f"/components/{component_id}"))
+    except ApiClientError as err:
+        handle_api_error("获取组件失败", err)
+
+
+@component_group.command("create")
+@click.option("--name")
+@click.option("--import-name")
+@click.option("--file", "file_path", type=click.Path(exists=True, dir_okay=False))
+@click.option("--type", "component_type", default="content")
+@click.option("--description")
+@click.option("--preview-schema-file", type=click.Path(exists=True, dir_okay=False))
+@click.option("--payload-file", type=click.Path(exists=True, dir_okay=False))
+@click.option("--wait/--no-wait", default=True)
+@click.option("--timeout", type=float, default=120.0, show_default=True)
+@idempotency_key_option
+@click.pass_context
+def create_component_cmd(
+    ctx: click.Context,
+    name: str | None,
+    import_name: str | None,
+    file_path: str | None,
+    component_type: str,
+    description: str | None,
+    preview_schema_file: str | None,
+    payload_file: str | None,
+    wait: bool,
+    timeout: float,
+) -> None:
+    """提交组件创建 Mutation Job。"""
+
+    profile = get_profile(load_config(), ctx.obj.get("profile"))
+    workspace_id = ctx.obj.get("workspace_id") or profile.default_workspace_id
+    if not workspace_id:
+        raise click.UsageError("必须通过 --workspace 或 Profile 默认配置指定工作空间。")
+    if payload_file:
+        payload = require_object(read_json_file(payload_file, label="组件创建载荷"), label="组件创建载荷")
+    else:
+        if not name or not import_name or not file_path:
+            raise click.UsageError("未使用 --payload-file 时必须提供 --name、--import-name 和 --file。")
+        payload = {
+            "workspace_id": workspace_id,
+            "import_name": import_name,
+            "name": name,
+            "component_type": component_type,
+            "source_code": read_text_file(file_path, label="组件源码"),
+            "description": description,
+        }
+    if preview_schema_file:
+        payload["preview_schema"] = read_json_file(preview_schema_file, label="Preview Schema")
+    try:
+        client = get_client(ctx)
+        result = resolve_wait_job(client, client.create_component(payload), wait=wait, timeout=timeout)
+        if wait:
+            require_success_job(result, ctx=ctx)
+        output_result(ctx, result)
+    except ApiClientError as err:
+        handle_api_error("提交组件创建失败", err)
+
+
+@component_group.command("update")
+@click.argument("component_id", type=int)
+@click.option("--payload-file", type=click.Path(exists=True, dir_okay=False), required=True)
+@click.option("--preview-schema-file", type=click.Path(exists=True, dir_okay=False), help="覆盖 payload 中的 Preview Schema JSON")
+@click.option("--wait/--no-wait", default=True)
+@click.option("--timeout", type=float, default=120.0, show_default=True)
+@idempotency_key_option
+@click.pass_context
+def update_component_cmd(
+    ctx: click.Context,
+    component_id: int,
+    payload_file: str,
+    preview_schema_file: str | None,
+    wait: bool,
+    timeout: float,
+) -> None:
+    """更新组件元数据，复杂字段自动进入异步校验任务。"""
+
+    payload = require_object(read_json_file(payload_file, label="组件更新载荷"), label="组件更新载荷")
+    if preview_schema_file:
+        payload["preview_schema"] = require_object(
+            read_json_file(preview_schema_file, label="Preview Schema"),
+            label="Preview Schema",
+        )
+    try:
+        client = get_client(ctx)
+        if any(field in payload for field in ("import_name", "component_type", "preview_schema")):
+            job = client.update_component_metadata_async({"component_id": component_id, **payload})
+            result = resolve_wait_job(client, job, wait=wait, timeout=timeout)
+            if wait:
+                require_success_job(result, ctx=ctx)
+            output_result(ctx, result)
+            return
+        output_result(ctx, client.patch(f"/components/{component_id}", json_data=payload))
+    except ApiClientError as err:
+        handle_api_error("更新组件失败", err)
+
+
+@component_group.command("edit")
+@click.argument("component_id", type=int)
+@click.option("--edits-file", type=click.Path(exists=True, dir_okay=False), required=True)
+@click.option("--base-version-no", type=int, required=True)
+@click.option("--base-draft-hash", required=True)
+@click.option("--wait/--no-wait", default=True)
+@click.option("--timeout", type=float, default=120.0, show_default=True)
+@idempotency_key_option
+@click.pass_context
+def edit_component_cmd(ctx: click.Context, component_id: int, edits_file: str, base_version_no: int, base_draft_hash: str, wait: bool, timeout: float) -> None:
+    """提交组件源码结构化编辑任务。"""
+
+    edits = require_array(read_json_file(edits_file, label="组件编辑操作"), label="组件编辑操作")
+    try:
+        client = get_client(ctx)
+        payload = {"component_id": component_id, "base_version_no": base_version_no, "base_draft_hash": base_draft_hash, "edits": edits}
+        result = resolve_wait_job(client, client.edit_component(component_id, payload), wait=wait, timeout=timeout)
+        if wait:
+            require_success_job(result, ctx=ctx)
+        output_result(ctx, result)
+    except ApiClientError as err:
+        handle_api_error("提交组件编辑失败", err)
+
+
+@component_group.group("version")
+def component_version_group() -> None:
+    """组件历史发布版本。"""
+
+
+@component_version_group.command("list")
+@click.argument("component_id", type=int)
+@click.pass_context
+def list_component_versions_cmd(ctx: click.Context, component_id: int) -> None:
+    """列出组件版本。"""
+
+    try:
+        output_result(ctx, get_client(ctx).get(f"/components/{component_id}/versions"))
+    except ApiClientError as err:
+        handle_api_error("获取组件版本失败", err)
+
+
+@component_version_group.command("get")
+@click.argument("component_id", type=int)
+@click.argument("version_no", type=int)
+@click.pass_context
+def get_component_version_cmd(ctx: click.Context, component_id: int, version_no: int) -> None:
+    """获取组件指定版本。"""
+
+    try:
+        output_result(ctx, get_client(ctx).get(f"/components/{component_id}/versions/{version_no}"))
+    except ApiClientError as err:
+        handle_api_error("获取组件版本内容失败", err)
+
+
+@component_group.command("dependencies")
+@click.argument("component_id", type=int)
+@click.pass_context
+def component_dependencies_cmd(ctx: click.Context, component_id: int) -> None:
+    """获取组件当前版本依赖。"""
+
+    try:
+        output_result(ctx, get_client(ctx).get(f"/components/{component_id}/dependencies"))
+    except ApiClientError as err:
+        handle_api_error("获取组件依赖失败", err)
+
+
+@component_group.command("validate")
+@click.argument("component_id", type=int)
+@click.option("--mode", type=click.Choice(["current", "content", "edits"]), default="current")
+@click.option("--source-file", type=click.Path(exists=True, dir_okay=False))
+@click.option("--edits-file", type=click.Path(exists=True, dir_okay=False))
+@click.option("--preview-schema-file", type=click.Path(exists=True, dir_okay=False))
+@click.option("--detail", is_flag=True)
+@click.pass_context
+def validate_component_cmd(ctx: click.Context, component_id: int, mode: str, source_file: str | None, edits_file: str | None, preview_schema_file: str | None, detail: bool) -> None:
+    """校验组件当前或候选源码。"""
+
+    payload: dict[str, object] = {"entity_type": "component", "entity_id": component_id, "mode": mode, "detail": detail}
+    if mode == "content":
+        if not source_file:
+            raise click.UsageError("content 模式必须提供 --source-file。")
+        payload["source_code"] = read_text_file(source_file, label="组件源码")
+    if mode == "edits":
+        if not edits_file:
+            raise click.UsageError("edits 模式必须提供 --edits-file。")
+        payload["edits"] = require_array(read_json_file(edits_file, label="组件编辑操作"), label="组件编辑操作")
+    if preview_schema_file:
+        payload["preview_schema"] = require_object(read_json_file(preview_schema_file, label="Preview Schema"), label="Preview Schema")
+    try:
+        output_result(ctx, get_client(ctx).validate_entity(payload))
+    except ApiClientError as err:
+        handle_api_error("组件校验失败", err)
+
+
+@component_group.command("publish")
+@click.argument("component_id", type=int)
+@click.option("--release-name")
+@click.option("--change-note")
+@idempotency_key_option
+@click.pass_context
+def publish_component_cmd(ctx: click.Context, component_id: int, release_name: str | None, change_note: str | None) -> None:
+    """发布组件当前草稿。"""
+
+    try:
+        output_result(ctx, get_client(ctx).post(f"/components/{component_id}/publish", json_data={"release_name": release_name, "change_note": change_note}))
+    except ApiClientError as err:
+        handle_api_error("发布组件失败", err)
+
+
+@component_group.command("archive")
+@click.argument("component_id", type=int, required=False)
+@click.option("--ids-file", type=click.Path(exists=True, dir_okay=False))
+@click.option("--yes", is_flag=True)
+@idempotency_key_option
+@click.pass_context
+def archive_component_cmd(ctx: click.Context, component_id: int | None, ids_file: str | None, yes: bool) -> None:
+    """归档单个或一批组件。"""
+
+    try:
+        client = get_client(ctx)
+        if ids_file:
+            ids = require_ids(read_json_file(ids_file, label="归档 ID"))
+            confirm_archive(ids, yes=yes, label="组件")
+            output_result(ctx, client.post("/components/batch-archive", json_data={"ids": ids}))
+            return
+        if component_id is None:
+            raise click.UsageError("必须提供 component_id 或 --ids-file。")
+        confirm_archive([component_id], yes=yes, label="组件")
+        output_result(ctx, client.post(f"/components/{component_id}/archive"))
+    except ApiClientError as err:
+        handle_api_error("归档组件失败", err)

wp/commands/doctor.py

@@ -0,0 +1,84 @@
+"""文件功能：执行 CLI 诊断（连通性、PAT 有效性、默认空间与权限检测）。"""
+
+from __future__ import annotations
+
+import click
+import httpx
+
+import wp
+from wp.client import ApiClient, ApiClientError
+from wp.config import get_profile, load_config
+from wp.formatter import print_json, print_table
+
+
+@click.command("doctor")
+@click.pass_context
+def doctor_cmd(ctx: click.Context) -> None:
+    """全面诊断本地 CLI 环境、服务连通性与 PAT 授权状态。"""
+
+    cfg = load_config()
+    profile = get_profile(cfg, ctx.obj.get("profile"))
+    diagnostics: list[dict[str, str]] = []
+
+    # 1. CLI 版本
+    diagnostics.append({"check": "CLI 版本", "value": f"v{wp.__version__}", "status": "ok"})
+
+    # 2. 服务端探活
+    endpoint = profile.endpoint.rstrip("/")
+    health_value = "不可达"
+    health_status = "error"
+    try:
+        r = httpx.get(f"{endpoint}/api/v1/system/health", timeout=5.0)
+        if r.status_code == 200:
+            health = r.json()
+            health_data = health if isinstance(health, dict) else {}
+            backend_status = str(health_data.get("status", "unknown"))
+            health_value = (
+                f"{backend_status}（database={health_data.get('database')}, "
+                f"redis={health_data.get('redis')}）"
+            )
+            health_status = "ok" if backend_status == "ok" else "warning"
+        else:
+            health_value = f"HTTP {r.status_code}"
+    except (httpx.RequestError, ValueError) as exc:
+        health_value = str(exc) or health_value
+    diagnostics.append({"check": "Backend 地址", "value": f"{endpoint}：{health_value}", "status": health_status})
+
+    # 3. PAT 凭证检测
+    token_status = "未配置"
+    if profile.token:
+        token_status = "已配置"
+    diagnostics.append(
+        {
+            "check": "访问令牌 (PAT)",
+            "value": token_status,
+            "status": "ok" if profile.token else "warning",
+        }
+    )
+
+    # 4. API 连通与权限校验
+    if profile.token:
+        client = ApiClient(profile)
+        try:
+            workspaces = client.get("/workspaces")
+            diagnostics.append({"check": "授权工作空间", "value": f"{len(workspaces)} 个可用空间", "status": "ok"})
+        except ApiClientError as err:
+            diagnostics.append({"check": "API 认证", "value": f"认证失败: {err.message}", "status": "error"})
+
+        ws_id = profile.default_workspace_id
+        if ws_id:
+            try:
+                ws = client.get(f"/workspaces/{ws_id}")
+                diagnostics.append({"check": "默认工作空间", "value": f"{ws.get('name')} (ID: {ws_id})", "status": "ok"})
+            except ApiClientError:
+                diagnostics.append({"check": "默认工作空间", "value": f"访问受限 (ID: {ws_id})", "status": "error"})
+        else:
+            diagnostics.append({"check": "默认工作空间", "value": "未设置，请使用 wp workspace use <id>", "status": "warning"})
+
+    if ctx.obj.get("as_json"):
+        print_json(diagnostics)
+        return
+
+    status_labels = {"ok": "正常", "warning": "警告", "error": "失败"}
+    rows = [[item["check"], item["value"], status_labels.get(item["status"], item["status"])] for item in diagnostics]
+    print_table("CLI 诊断检查报告", ["检查项", "当前状态", "判定结果"], rows)

wp/commands/job.py

@@ -0,0 +1,84 @@
+"""文件功能：提供统一的异步 Mutation Job 查询、等待、取消与重试命令。"""
+
+from __future__ import annotations
+
+import click
+
+from wp.client import ApiClientError
+from wp.commands.common import (
+    get_client,
+    handle_api_error,
+    idempotency_key_option,
+    output_result,
+    require_success_job,
+)
+
+
+@click.group("job")
+def job_group() -> None:
+    """异步任务管理。"""
+
+
+@job_group.command("get")
+@click.argument("job_id")
+@click.pass_context
+def get_job_cmd(ctx: click.Context, job_id: str) -> None:
+    """查询 Mutation Job。"""
+
+    try:
+        output_result(ctx, get_client(ctx).get_mutation_job(job_id))
+    except ApiClientError as err:
+        handle_api_error("查询 Job 失败", err)
+
+
+@job_group.command("wait")
+@click.argument("job_id")
+@click.option("--timeout", default=120.0, type=float, show_default=True)
+@click.pass_context
+def wait_job_cmd(ctx: click.Context, job_id: str, timeout: float) -> None:
+    """等待 Mutation Job 进入终态。"""
+
+    try:
+        result = get_client(ctx).poll_mutation_job(job_id, timeout_seconds=timeout)
+        require_success_job(result, ctx=ctx)
+        output_result(ctx, result)
+    except ApiClientError as err:
+        handle_api_error("等待 Job 失败", err)
+
+
+@job_group.command("cancel")
+@click.argument("job_id")
+@idempotency_key_option
+@click.pass_context
+def cancel_job_cmd(ctx: click.Context, job_id: str) -> None:
+    """取消 pending 或 running Mutation Job。"""
+
+    try:
+        output_result(
+            ctx,
+            get_client(ctx).cancel_mutation_job(
+                job_id,
+                idempotency_key=ctx.obj.get("idempotency_key"),
+            ),
+        )
+    except ApiClientError as err:
+        handle_api_error("取消 Job 失败", err)
+
+
+@job_group.command("retry")
+@click.argument("job_id")
+@idempotency_key_option
+@click.pass_context
+def retry_job_cmd(ctx: click.Context, job_id: str) -> None:
+    """重试一个明确允许人工重试的失败 Job。"""
+
+    try:
+        output_result(
+            ctx,
+            get_client(ctx).retry_mutation_job(
+                job_id,
+                idempotency_key=ctx.obj.get("idempotency_key"),
+            ),
+        )
+    except ApiClientError as err:
+        handle_api_error("重试 Job 失败", err)