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

wp/commands/screenshot.py

@@ -0,0 +1,73 @@
+"""文件功能：提供页面最新截图获取与保存命令，自动触发服务端刷新并返回最新截图。"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import uuid
+
+import click
+
+from wp.client import ApiClient, ApiClientError
+from wp.config import get_profile, load_config
+from wp.formatter import print_error, print_json, print_success, print_table
+
+
+@click.command("screenshot")
+@click.argument("page_id", type=int)
+@click.option("--output", "-o", help="截图输出保存路径 (默认保存为 page-<page_id>-v<version>.png)")
+@click.pass_context
+def screenshot_cmd(
+    ctx: click.Context,
+    page_id: int,
+    output: str | None,
+) -> None:
+    """获取指定页面的最新截图（像视觉分析工具一样，自动在服务端刷新并返回最新 PNG 截图）。"""
+
+    cfg = load_config()
+    profile = get_profile(cfg, ctx.obj.get("profile"))
+    client = ApiClient(profile, workspace_id=ctx.obj.get("workspace_id"))
+
+    try:
+        page_meta, img_bytes = client.get_latest_page_screenshot(page_id=page_id)
+
+        version_no = page_meta.get("version_no") or 1
+        save_path = Path(output) if output else Path(f"page-{page_id}-v{version_no}.png")
+        tmp_path = save_path.with_name(f".{save_path.name}.tmp.{uuid.uuid4().hex[:8]}")
+
+        try:
+            save_path.parent.mkdir(parents=True, exist_ok=True)
+            tmp_path.write_bytes(img_bytes)
+            os.replace(tmp_path, save_path)
+        except OSError as exc:
+            if tmp_path.exists():
+                try:
+                    tmp_path.unlink()
+                except OSError:
+                    pass
+            print_error(f"写入截图文件 '{save_path}' 失败: {exc}")
+            raise SystemExit(1)
+
+        result_payload = {
+            "page_id": page_id,
+            "version_no": version_no,
+            "saved_file": str(save_path.resolve()),
+            "size_bytes": len(img_bytes),
+        }
+
+        if ctx.obj.get("as_json"):
+            print_json(result_payload)
+            return
+
+        print_success(f"成功获取页面 (ID: {page_id}) 最新截图并保存至 [bold]{save_path}[/bold]")
+        rows = [
+            ["页面 ID", str(page_id)],
+            ["页面版本", f"v{version_no}"],
+            ["文件大小", f"{len(img_bytes)} 字节"],
+            ["保存路径", str(save_path.resolve())],
+        ]
+        print_table("最新页面截图信息", ["属性", "值"], rows)
+
+    except ApiClientError as err:
+        print_error(f"获取最新截图失败: {err.message}", code=err.code)
+        raise SystemExit(1)

wp/commands/style.py

@@ -0,0 +1,155 @@
+"""文件功能：处理样式方案管理（列表、详情、创建、复制、归档）。"""
+
+from __future__ import annotations
+
+import click
+
+from wp.client import ApiClient, ApiClientError
+from wp.config import get_profile, load_config
+from wp.formatter import print_error, print_json, print_success, print_table
+from wp.commands.common import (
+    confirm_archive,
+    get_client,
+    handle_api_error,
+    idempotency_key_option,
+    output_result,
+    read_json_file,
+    require_ids,
+    require_object,
+)
+
+
+@click.group("style")
+def style_group() -> None:
+    """工作空间样式方案管理。"""
+
+
+@style_group.command("list")
+@click.option("--page", default=1, type=int, help="页码")
+@click.option("--page-size", default=50, type=int, help="每页数量")
+@click.pass_context
+def list_styles_cmd(ctx: click.Context, page: int, page_size: int) -> None:
+    """查询工作空间的样式方案列表。"""
+
+    cfg = load_config()
+    profile = get_profile(cfg, ctx.obj.get("profile"))
+    client = ApiClient(profile, workspace_id=ctx.obj.get("workspace_id"))
+
+    try:
+        res = client.get("/styles", params={"page": page, "page_size": page_size})
+        if ctx.obj.get("as_json"):
+            print_json(res)
+            return
+
+        items = res.get("items", [])
+        rows = [[s["id"], s.get("name", "-"), s.get("is_default", False), s.get("status", "-")] for s in items]
+        print_table("样式方案列表", ["ID", "名称", "是否默认", "状态"], rows)
+    except ApiClientError as err:
+        print_error(f"获取样式列表失败: {err.message}", code=err.code)
+        raise SystemExit(1)
+
+
+@style_group.command("get")
+@click.argument("style_id", type=int)
+@click.pass_context
+def get_style_cmd(ctx: click.Context, style_id: int) -> None:
+    """获取单个样式方案详情。"""
+
+    cfg = load_config()
+    profile = get_profile(cfg, ctx.obj.get("profile"))
+    client = ApiClient(profile, workspace_id=ctx.obj.get("workspace_id"))
+
+    try:
+        style = client.get(f"/styles/{style_id}")
+        if ctx.obj.get("as_json"):
+            print_json(style)
+            return
+
+        rows = [
+            ["ID", str(style.get("id"))],
+            ["名称", str(style.get("name"))],
+            ["是否默认", str(style.get("is_default"))],
+            ["描述", str(style.get("description") or "-")],
+            ["状态", str(style.get("status"))],
+        ]
+        print_table(f"样式方案 (ID: {style_id}) 详情", ["属性", "值"], rows)
+    except ApiClientError as err:
+        print_error(f"获取样式方案失败: {err.message}", code=err.code)
+        raise SystemExit(1)
+
+
+@style_group.command("create")
+@click.option("--name", "-n", help="样式方案名称")
+@click.option("--description", "-d", help="样式描述")
+@click.option(
+    "--payload-file",
+    type=click.Path(exists=True, dir_okay=False),
+    help="完整样式创建 JSON；支持 configuration.presentation 或顶层 page_width 等展示字段",
+)
+@idempotency_key_option
+@click.pass_context
+def create_style_cmd(ctx: click.Context, name: str | None, description: str | None, payload_file: str | None) -> None:
+    """创建新样式方案。"""
+
+    try:
+        if payload_file:
+            payload = require_object(read_json_file(payload_file, label="样式创建载荷"), label="样式创建载荷")
+        else:
+            if not name:
+                raise click.UsageError("未使用 --payload-file 时必须提供 --name。")
+            payload = {"name": name, "description": description}
+        output_result(ctx, get_client(ctx).post("/styles", json_data=payload))
+    except ApiClientError as err:
+        handle_api_error("创建样式方案失败", err)
+
+
+@style_group.command("update")
+@click.argument("style_id", type=int)
+@click.option("--payload-file", type=click.Path(exists=True, dir_okay=False), required=True)
+@idempotency_key_option
+@click.pass_context
+def update_style_cmd(ctx: click.Context, style_id: int, payload_file: str) -> None:
+    """更新样式元数据和 configuration。"""
+
+    try:
+        output_result(ctx, get_client(ctx).patch(f"/styles/{style_id}", json_data=require_object(read_json_file(payload_file, label="样式更新载荷"), label="样式更新载荷")))
+    except ApiClientError as err:
+        handle_api_error("更新样式失败", err)
+
+
+@style_group.command("copy")
+@click.argument("style_id", type=int)
+@click.option("--payload-file", type=click.Path(exists=True, dir_okay=False), required=True)
+@idempotency_key_option
+@click.pass_context
+def copy_style_cmd(ctx: click.Context, style_id: int, payload_file: str) -> None:
+    """复制样式方案。"""
+
+    try:
+        output_result(ctx, get_client(ctx).post(f"/styles/{style_id}/copy", json_data=require_object(read_json_file(payload_file, label="样式复制载荷"), label="样式复制载荷")))
+    except ApiClientError as err:
+        handle_api_error("复制样式失败", err)
+
+
+@style_group.command("archive")
+@click.argument("style_id", type=int, required=False)
+@click.option("--ids-file", type=click.Path(exists=True, dir_okay=False))
+@click.option("--yes", "-y", is_flag=True, help="跳过确认直接归档")
+@idempotency_key_option
+@click.pass_context
+def archive_style_cmd(ctx: click.Context, style_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("/styles/batch-archive", json_data={"ids": ids}))
+            return
+        if style_id is None:
+            raise click.UsageError("必须提供 style_id 或 --ids-file。")
+        confirm_archive([style_id], yes=yes, label="样式")
+        output_result(ctx, client.post(f"/styles/{style_id}/archive"))
+    except ApiClientError as err:
+        handle_api_error("归档样式方案失败", err)

wp/commands/system.py

@@ -0,0 +1,93 @@
+"""文件功能：提供系统探活、开发标准和 External API 操作指南命令。"""
+
+from __future__ import annotations
+
+import click
+
+from wp.client import ApiClientError
+from wp.commands.common import get_client, handle_api_error, output_result
+
+
+@click.group("system")
+def system_group() -> None:
+    """系统信息与健康检查。"""
+
+
+@system_group.command("version")
+@click.pass_context
+def system_version_cmd(ctx: click.Context) -> None:
+    """获取 Backend 与 External API 版本。"""
+
+    try:
+        output_result(ctx, get_client(ctx).get("/system/version"))
+    except ApiClientError as err:
+        handle_api_error("获取系统版本失败", err)
+
+
+@system_group.command("health")
+@click.pass_context
+def system_health_cmd(ctx: click.Context) -> None:
+    """检查 Backend 数据库和 Redis 健康状态。"""
+
+    try:
+        output_result(ctx, get_client(ctx).get("/system/health"))
+    except ApiClientError as err:
+        handle_api_error("检查系统健康失败", err)
+
+
+@click.group("standards")
+def standards_group() -> None:
+    """读取页面和组件开发标准。"""
+
+
+def _standard(entity_type: str, ctx: click.Context) -> None:
+    """读取指定资源的标准规范。"""
+
+    try:
+        output_result(ctx, get_client(ctx).get_standard(entity_type))
+    except ApiClientError as err:
+        handle_api_error("读取开发标准失败", err)
+
+
+@standards_group.command("page")
+@click.pass_context
+def page_standards_cmd(ctx: click.Context) -> None:
+    """读取页面开发标准。"""
+
+    _standard("page", ctx)
+
+
+@standards_group.command("component")
+@click.pass_context
+def component_standards_cmd(ctx: click.Context) -> None:
+    """读取组件开发标准。"""
+
+    _standard("component", ctx)
+
+
+@click.group("guide")
+def guide_group() -> None:
+    """读取 External API 操作指南。"""
+
+
+@guide_group.command("list")
+@click.pass_context
+def guide_list_cmd(ctx: click.Context) -> None:
+    """列出当前 External API 操作。"""
+
+    try:
+        output_result(ctx, get_client(ctx).get_operation_guide())
+    except ApiClientError as err:
+        handle_api_error("获取操作指南列表失败", err)
+
+
+@guide_group.command("get")
+@click.argument("operation_key")
+@click.pass_context
+def guide_get_cmd(ctx: click.Context, operation_key: str) -> None:
+    """获取单个 External API 操作的 HTTP 与 JSON Schema 契约。"""
+
+    try:
+        output_result(ctx, get_client(ctx).get_operation_guide(operation_key))
+    except ApiClientError as err:
+        handle_api_error("获取操作指南详情失败", err)

wp/commands/theme.py

@@ -0,0 +1,152 @@
+"""文件功能：处理主题管理（列表、详情、创建、复制、归档）。"""
+
+from __future__ import annotations
+
+import click
+
+from wp.client import ApiClient, ApiClientError
+from wp.config import get_profile, load_config
+from wp.formatter import print_error, print_json, print_success, print_table
+from wp.commands.common import (
+    confirm_archive,
+    get_client,
+    handle_api_error,
+    idempotency_key_option,
+    output_result,
+    read_json_file,
+    require_ids,
+    require_object,
+)
+
+
+@click.group("theme")
+def theme_group() -> None:
+    """工作空间主题管理。"""
+
+
+@theme_group.command("list")
+@click.option("--page", default=1, type=int, help="页码")
+@click.option("--page-size", default=50, type=int, help="每页数量")
+@click.pass_context
+def list_themes_cmd(ctx: click.Context, page: int, page_size: int) -> None:
+    """查询工作空间的主题列表。"""
+
+    cfg = load_config()
+    profile = get_profile(cfg, ctx.obj.get("profile"))
+    client = ApiClient(profile, workspace_id=ctx.obj.get("workspace_id"))
+
+    try:
+        res = client.get("/themes", params={"page": page, "page_size": page_size})
+        if ctx.obj.get("as_json"):
+            print_json(res)
+            return
+
+        items = res.get("items", [])
+        rows = [[t["id"], t.get("key", "-"), t.get("name", "-"), t.get("status", "-")] for t in items]
+        print_table("主题列表", ["ID", "Key", "名称", "状态"], rows)
+    except ApiClientError as err:
+        print_error(f"获取主题列表失败: {err.message}", code=err.code)
+        raise SystemExit(1)
+
+
+@theme_group.command("get")
+@click.argument("theme_id", type=int)
+@click.pass_context
+def get_theme_cmd(ctx: click.Context, theme_id: int) -> None:
+    """获取单个主题详情。"""
+
+    cfg = load_config()
+    profile = get_profile(cfg, ctx.obj.get("profile"))
+    client = ApiClient(profile, workspace_id=ctx.obj.get("workspace_id"))
+
+    try:
+        theme = client.get(f"/themes/{theme_id}")
+        if ctx.obj.get("as_json"):
+            print_json(theme)
+            return
+
+        rows = [
+            ["ID", str(theme.get("id"))],
+            ["Key", str(theme.get("key"))],
+            ["名称", str(theme.get("name"))],
+            ["描述", str(theme.get("description") or "-")],
+            ["状态", str(theme.get("status"))],
+        ]
+        print_table(f"主题 (ID: {theme_id}) 详情", ["属性", "值"], rows)
+    except ApiClientError as err:
+        print_error(f"获取主题失败: {err.message}", code=err.code)
+        raise SystemExit(1)
+
+
+@theme_group.command("create")
+@click.option("--key", "-k", help="主题唯一标识 (例如 light-corporate)")
+@click.option("--name", "-n", help="主题名称")
+@click.option("--description", "-d", help="主题描述")
+@click.option("--payload-file", type=click.Path(exists=True, dir_okay=False), help="完整主题 JSON 请求体")
+@idempotency_key_option
+@click.pass_context
+def create_theme_cmd(ctx: click.Context, key: str | None, name: str | None, description: str | None, payload_file: str | None) -> None:
+    """创建新主题。"""
+
+    try:
+        if payload_file:
+            payload = require_object(read_json_file(payload_file, label="主题创建载荷"), label="主题创建载荷")
+        else:
+            if not key or not name:
+                raise click.UsageError("未使用 --payload-file 时必须提供 --key 和 --name。")
+            payload = {"key": key, "name": name, "description": description}
+        output_result(ctx, get_client(ctx).post("/themes", json_data=payload))
+    except ApiClientError as err:
+        handle_api_error("创建主题失败", err)
+
+
+@theme_group.command("update")
+@click.argument("theme_id", type=int)
+@click.option("--payload-file", type=click.Path(exists=True, dir_okay=False), required=True)
+@idempotency_key_option
+@click.pass_context
+def update_theme_cmd(ctx: click.Context, theme_id: int, payload_file: str) -> None:
+    """更新主题名称、描述和色板。"""
+
+    try:
+        output_result(ctx, get_client(ctx).patch(f"/themes/{theme_id}", json_data=require_object(read_json_file(payload_file, label="主题更新载荷"), label="主题更新载荷")))
+    except ApiClientError as err:
+        handle_api_error("更新主题失败", err)
+
+
+@theme_group.command("copy")
+@click.argument("theme_id", type=int)
+@click.option("--payload-file", type=click.Path(exists=True, dir_okay=False), required=True)
+@idempotency_key_option
+@click.pass_context
+def copy_theme_cmd(ctx: click.Context, theme_id: int, payload_file: str) -> None:
+    """复制主题。"""
+
+    try:
+        output_result(ctx, get_client(ctx).post(f"/themes/{theme_id}/copy", json_data=require_object(read_json_file(payload_file, label="主题复制载荷"), label="主题复制载荷")))
+    except ApiClientError as err:
+        handle_api_error("复制主题失败", err)
+
+
+@theme_group.command("archive")
+@click.argument("theme_id", type=int, required=False)
+@click.option("--ids-file", type=click.Path(exists=True, dir_okay=False))
+@click.option("--yes", "-y", is_flag=True, help="跳过确认直接归档")
+@idempotency_key_option
+@click.pass_context
+def archive_theme_cmd(ctx: click.Context, theme_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("/themes/batch-archive", json_data={"ids": ids}))
+            return
+        if theme_id is None:
+            raise click.UsageError("必须提供 theme_id 或 --ids-file。")
+        confirm_archive([theme_id], yes=yes, label="主题")
+        output_result(ctx, client.post(f"/themes/{theme_id}/archive"))
+    except ApiClientError as err:
+        handle_api_error("归档主题失败", err)

wp/commands/workspace.py

@@ -0,0 +1,89 @@
+"""文件功能：处理工作空间列表查询、默认空间切换与能力矩阵发现。"""
+
+from __future__ import annotations
+
+import click
+
+from wp.client import ApiClient, ApiClientError
+from wp.config import get_profile, load_config, save_config
+from wp.formatter import print_error, print_json, print_success, print_table
+
+
+@click.group("workspace")
+def workspace_group() -> None:
+    """工作空间操作。"""
+
+
+@workspace_group.command("list")
+@click.pass_context
+def list_workspaces_cmd(ctx: click.Context) -> None:
+    """列出当前令牌可访问的所有工作空间。"""
+
+    cfg = load_config()
+    profile = get_profile(cfg, ctx.obj.get("profile"))
+    client = ApiClient(profile)
+
+    try:
+        workspaces = client.get("/workspaces")
+        if ctx.obj.get("as_json"):
+            print_json(workspaces)
+            return
+
+        current_ws_id = profile.default_workspace_id
+        rows = []
+        for w in workspaces:
+            is_curr = "*" if w["id"] == current_ws_id else ""
+            rows.append([f"{is_curr} {w['id']}", w["name"], w.get("code") or "-", w.get("status")])
+
+        print_table("授权工作空间 (* 当前默认)", ["ID", "名称", "Code", "状态"], rows)
+    except ApiClientError as err:
+        print_error(f"获取工作空间失败: {err.message}", code=err.code)
+        raise SystemExit(1)
+
+
+@workspace_group.command("use")
+@click.argument("workspace_id", type=int)
+@click.pass_context
+def use_workspace_cmd(ctx: click.Context, workspace_id: int) -> None:
+    """切换本地默认操作的工作空间 ID。"""
+
+    cfg = load_config()
+    profile = get_profile(cfg, ctx.obj.get("profile"))
+    client = ApiClient(profile)
+
+    try:
+        ws = client.get(f"/workspaces/{workspace_id}")
+        profile.default_workspace_id = workspace_id
+        save_config(cfg)
+        print_success(f"已将默认工作空间切换为: [bold]{ws.get('name')}[/bold] (ID: {workspace_id})")
+    except ApiClientError as err:
+        print_error(f"切换工作空间失败: {err.message}", code=err.code)
+        raise SystemExit(1)
+
+
+@workspace_group.command("capabilities")
+@click.option("--workspace-id", "-w", type=int, help="工作空间 ID")
+@click.pass_context
+def get_capabilities_cmd(ctx: click.Context, workspace_id: int | None) -> None:
+    """查询当前令牌在指定工作空间的能力矩阵与可用操作列表。"""
+
+    cfg = load_config()
+    profile = get_profile(cfg, ctx.obj.get("profile"))
+    ws_id = workspace_id or ctx.obj.get("workspace_id") or profile.default_workspace_id
+    if not ws_id:
+        print_error("未指定工作空间 ID，请先使用 `wp workspace use <id>` 或提供 `-w <id>`。")
+        raise SystemExit(1)
+
+    client = ApiClient(profile, workspace_id=ws_id)
+    try:
+        caps = client.get(f"/workspaces/{ws_id}/capabilities")
+        if ctx.obj.get("as_json"):
+            print_json(caps)
+            return
+
+        print_success(f"工作空间 (ID: {ws_id}) 权限能力:")
+        print_table("授权 Scope", ["Scope 标识"], [[s] for s in caps.get("scopes", [])])
+        print_table("可用操作 (Operations)", ["操作 Key"], [[op] for op in caps.get("operations", [])])
+    except ApiClientError as err:
+        print_error(f"查询能力矩阵失败: {err.message}", code=err.code)
+        raise SystemExit(1)

wp/config.py

@@ -0,0 +1,91 @@
+"""文件功能：管理 CLI 本地配置文件与多 Profile 切换（存储在 ~/.web-presentation/config.json）。"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+import tempfile
+import time
+
+from pydantic import BaseModel, Field, ValidationError
+
+CONFIG_DIR = Path.home() / ".web-presentation"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+DEFAULT_PROFILE = "default"
+DEFAULT_ENDPOINT = "http://127.0.0.1:8000"
+
+
+class ProfileConfig(BaseModel):
+    """单个环境 Profile 配置项。"""
+
+    endpoint: str = Field(default=DEFAULT_ENDPOINT)
+    token: str | None = Field(default=None)
+    default_workspace_id: int | None = Field(default=None)
+
+
+class CliConfig(BaseModel):
+    """CLI 全局配置文件。"""
+
+    current_profile: str = Field(default=DEFAULT_PROFILE)
+    profiles: dict[str, ProfileConfig] = Field(
+        default_factory=lambda: {DEFAULT_PROFILE: ProfileConfig()}
+    )
+
+
+def load_config() -> CliConfig:
+    """加载本地配置文件；若不存在则自动初始化默认配置。"""
+
+    if not CONFIG_FILE.exists():
+        return CliConfig()
+
+    try:
+        data = json.loads(CONFIG_FILE.read_text(encoding="utf-8"))
+        return CliConfig.model_validate(data)
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError, ValidationError):
+        # 配置损坏时先保留现场，避免后续 login/logout 覆盖掉其它 Profile。
+        backup_path = CONFIG_FILE.with_name(f"{CONFIG_FILE.name}.corrupt.{time.time_ns()}")
+        try:
+            CONFIG_FILE.replace(backup_path)
+        except OSError:
+            pass
+        return CliConfig()
+
+
+def save_config(config: CliConfig) -> None:
+    """持久化保存本地配置文件（在 POSIX 系统上设置 0600 权限防止凭据泄露）。"""
+
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    content = json.dumps(config.model_dump(mode="json"), indent=2, ensure_ascii=False)
+    temp_path: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            encoding="utf-8",
+            dir=CONFIG_DIR,
+            prefix=".config.",
+            suffix=".tmp",
+            delete=False,
+        ) as temp_file:
+            temp_path = Path(temp_file.name)
+            temp_file.write(content)
+            temp_file.flush()
+            if os.name != "nt":
+                temp_path.chmod(0o600)
+        os.replace(temp_path, CONFIG_FILE)
+        temp_path = None
+    finally:
+        if temp_path is not None:
+            try:
+                temp_path.unlink()
+            except OSError:
+                pass
+
+
+def get_profile(config: CliConfig, profile_name: str | None = None) -> ProfileConfig:
+    """获取指定或当前的 Profile 配置。"""
+
+    name = profile_name or config.current_profile or DEFAULT_PROFILE
+    if name not in config.profiles:
+        config.profiles[name] = ProfileConfig()
+    return config.profiles[name]