@qingflow-tech/qingflow-cli 1.1.51 → 1.1.53

package/src/qingflow_mcp/builder_facade/views_schema.py

@@ -0,0 +1,400 @@
+from __future__ import annotations
+
+import json
+import os
+from copy import deepcopy
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from jsonschema import Draft202012Validator, FormatChecker
+from referencing import Registry, Resource
+
+from .app_form_schema import compact_schema_errors, schema_error_message
+
+JSONObject = dict[str, Any]
+VIEWS_SCHEMA_ROOT = Path(__file__).with_name("schemas") / "views"
+VIEWS_SUPPORTED_SCHEMA_KINDS = (
+    "summary",
+    "complete",
+    "display",
+    "data-permission",
+    "operation-permission",
+    "query-condition",
+    "button-config",
+)
+
+
+class ViewsContractError(ValueError):
+    """Raised when a views declaration violates the versioned schema contract."""
+
+    def __init__(self, error_code: str, message: str, *, path: str | None = None, details: JSONObject | None = None) -> None:
+        super().__init__(message)
+        self.error_code = error_code
+        self.message = message
+        self.path = path
+        self.details = details or {}
+
+
+def compact_none_values(value: Any) -> Any:
+    """Recursively drop None values so pydantic dumps match the JSON Schema contract."""
+    if isinstance(value, dict):
+        return {key: compact_none_values(item) for key, item in value.items() if item is not None}
+    if isinstance(value, list):
+        return [compact_none_values(item) for item in value]
+    return value
+
+
+@dataclass(frozen=True, slots=True)
+class ViewsSchemaContext:
+    """Resolved schema context for one views schema version."""
+
+    schema_version: str
+    api_version: str
+    schemas: dict[str, JSONObject]
+    schema_files: dict[str, str]
+    ref_registry: Registry
+    supported_schema_kinds: tuple[str, ...]
+    contract_source: str
+    contract_version: str
+
+    @property
+    def summary_schema(self) -> JSONObject:
+        return self.schemas["summary"]
+
+    @property
+    def complete_schema(self) -> JSONObject:
+        return self.schemas["complete"]
+
+    def schema_for_kind(self, schema_kind: str) -> JSONObject:
+        requested = str(schema_kind or "").strip()
+        schema = self.schemas.get(requested)
+        if schema is not None:
+            return schema
+        raise ViewsContractError(
+            "UNSUPPORTED_SCHEMA_KIND",
+            f"unsupported views schema kind: {requested}",
+            details={"supportedKinds": list(self.supported_schema_kinds)},
+        )
+
+    def _validate(self, payload: JSONObject, *, schema_kind: str) -> None:
+        schema = self.schema_for_kind(schema_kind)
+        validator = Draft202012Validator(schema, format_checker=FormatChecker(), registry=self.ref_registry)
+        errors = sorted(validator.iter_errors(payload), key=lambda item: (list(item.absolute_path), item.message))
+        if not errors:
+            return
+        compact_errors = compact_schema_errors(errors, schema)
+        error = compact_errors[0] if compact_errors else errors[0]
+        pointer = "".join(f"/{str(part).replace('~', '~0').replace('/', '~1')}" for part in error.absolute_path) or "/"
+        raise ViewsContractError(
+            "INVALID_SPEC",
+            schema_error_message(error),
+            path=pointer,
+            details={
+                "validator": error.validator,
+                "schemaPath": "/".join(str(part) for part in error.absolute_schema_path),
+                "schemaKind": schema_kind,
+            },
+        )
+
+    def validate_upsert(self, payload: JSONObject, *, schema_kind: str = "complete") -> None:
+        """Validate a single (alias-normalized) view declaration."""
+        self._validate(payload, schema_kind=schema_kind)
+
+    def validate_declaration(self, payload: JSONObject, *, schema_kind: str = "complete") -> None:
+        """Validate one view declaration used by ``app_views_apply.upsert_view``."""
+        if not isinstance(payload, dict):
+            raise ViewsContractError("INVALID_SPEC", "views declaration must be a JSON object", path="/")
+        batch_keys = ("views", "upsert_views", "upsertViews", "apps")
+        if any(key in payload for key in batch_keys):
+            raise ViewsContractError(
+                "VIEW_BATCH_CREATE_UNSUPPORTED",
+                "views schema validates one view declaration; batch envelopes are unsupported",
+                path="/",
+                details={"unsupportedKeys": [key for key in batch_keys if key in payload], "schemaKind": schema_kind},
+            )
+        self._validate(payload, schema_kind=schema_kind)
+
+class ViewsSchemaRegistry:
+    """Registry for versioned views declaration schemas (mirrors AppFormSchemaRegistry)."""
+
+    def __init__(self, root: Path = VIEWS_SCHEMA_ROOT, *, enabled_versions: tuple[str, ...] | None = None) -> None:
+        self.root = root
+        self.manifest = self._read_json(root / "manifest.json")
+        versions = self.manifest.get("versions")
+        if not isinstance(versions, dict) or not versions:
+            raise RuntimeError("views schema manifest must define versions")
+        env_versions = self._configured_versions()
+        defaults = tuple(
+            str(version)
+            for version, metadata in versions.items()
+            if isinstance(metadata, dict) and bool(metadata.get("enabledByDefault"))
+        )
+        configured = tuple(enabled_versions) if enabled_versions is not None else (env_versions or defaults)
+        self.stored_versions = tuple(str(version) for version in versions)
+        self.latest_version = str(self.manifest.get("latestVersion") or "")
+        self._stored_api_to_version: dict[str, str] = {}
+        for version, metadata in versions.items():
+            if not isinstance(metadata, dict):
+                raise RuntimeError(f"views schema metadata must be an object: {version}")
+            api_version = str(metadata.get("apiVersion") or "")
+            if not api_version:
+                raise RuntimeError(f"views schema version has no apiVersion: {version}")
+            if api_version in self._stored_api_to_version:
+                raise RuntimeError(f"duplicate views apiVersion: {api_version}")
+            self._stored_api_to_version[api_version] = str(version)
+        self.enabled_versions = configured
+        if self.latest_version not in versions:
+            raise RuntimeError("views latestVersion is not stored")
+        if self.latest_version not in self.enabled_versions:
+            raise RuntimeError("views latestVersion must remain enabled")
+        self._contexts: dict[str, ViewsSchemaContext] = {}
+        self._api_to_version: dict[str, str] = {}
+        for version in self.enabled_versions:
+            metadata = versions.get(version)
+            if not isinstance(metadata, dict):
+                raise RuntimeError(f"enabled views schema version is not stored: {version}")
+            api_version = str(metadata.get("apiVersion") or "")
+            schema_files = metadata.get("schemaFiles")
+            if not isinstance(schema_files, dict):
+                schema_files = {kind: f"{version}/{kind}.json" for kind in ("summary", "complete")}
+            supported_schema_kinds = tuple(str(item) for item in metadata.get("schemaKinds") or schema_files)
+            if not {"summary", "complete"}.issubset(supported_schema_kinds):
+                raise RuntimeError(f"views schema version must support summary and complete kinds: {version}")
+            schemas: dict[str, JSONObject] = {}
+            paths: dict[str, Path] = {}
+            for name in supported_schema_kinds:
+                relative_path = schema_files.get(name)
+                if not isinstance(relative_path, str) or not relative_path:
+                    raise RuntimeError(f"views schema kind has no schema file: {version}/{name}")
+                path = root / relative_path
+                schema = self._read_json(path)
+                schemas[name] = schema
+                paths[name] = path
+            ref_registry = Registry()
+            for name, schema in schemas.items():
+                schema_id = str(schema.get("$id") or "")
+                if version not in schema_id:
+                    raise RuntimeError(f"views {name} schema $id mismatch for {version}: {schema_id}")
+                Draft202012Validator.check_schema(schema)
+                resource = Resource.from_contents(schema)
+                if schema_id:
+                    ref_registry = ref_registry.with_resource(schema_id, resource)
+                ref_registry = ref_registry.with_resource(paths[name].resolve().as_uri(), resource)
+            for name, schema in schemas.items():
+                self._validate_local_refs(schema, paths[name], schemas, paths)
+            context = ViewsSchemaContext(
+                version,
+                api_version,
+                schemas,
+                {name: str(schema_files[name]) for name in supported_schema_kinds},
+                ref_registry,
+                supported_schema_kinds,
+                str(metadata.get("contractSource") or "app_views_apply"),
+                str(metadata.get("contractVersion") or version),
+            )
+            self._contexts[version] = context
+            self._api_to_version[api_version] = version
+
+    def schema(
+        self,
+        *,
+        schema_version: str | None = None,
+        schema_kind: str | None = None,
+    ) -> JSONObject:
+        context = self.resolve_schema_version(schema_version)
+        requested_kind = str(schema_kind or "summary").strip()
+        if requested_kind not in context.supported_schema_kinds:
+            raise ViewsContractError(
+                "UNSUPPORTED_SCHEMA_KIND",
+                f"unsupported views schema kind: {requested_kind}",
+                details={"supportedKinds": list(context.supported_schema_kinds)},
+            )
+        schema, dependencies = self._bundle_schema(
+            context.schema_for_kind(requested_kind),
+            schema_path=(self.root / context.schema_files[requested_kind]),
+            schemas=context.schemas,
+            schema_files=context.schema_files,
+        )
+        return {
+            "schemaVersion": context.schema_version,
+            "apiVersion": context.api_version,
+            "latestVersion": self.latest_version,
+            "storedVersions": list(self.stored_versions),
+            "enabledVersions": list(self.enabled_versions),
+            "supportedSchemaKinds": list(context.supported_schema_kinds),
+            "schemaKind": requested_kind,
+            "schemaFile": context.schema_files[requested_kind],
+            "schemaBundled": bool(dependencies),
+            "schemaDependencies": dependencies,
+            "schema": schema,
+        }
+
+    @classmethod
+    def _bundle_schema(
+        cls,
+        schema: JSONObject,
+        *,
+        schema_path: Path,
+        schemas: dict[str, JSONObject],
+        schema_files: dict[str, str],
+    ) -> tuple[JSONObject, list[str]]:
+        """Inline reachable cross-file definitions for standalone consumers."""
+        bundled = deepcopy(schema)
+        definitions = bundled.get("$defs")
+        if not isinstance(definitions, dict):
+            definitions = {}
+        dependencies: set[str] = set()
+        # schema_path is <root>/<version>/details/<file> or <root>/<version>/<file>.
+        # Find the manifest root from the configured path instead of relying on
+        # a fixed details depth.
+        cls_root = schema_path.parent
+        for candidate in schema_path.parents:
+            if (candidate / "manifest.json").is_file():
+                cls_root = candidate
+                break
+        paths = {name: cls_root / relative for name, relative in schema_files.items()}
+
+        def resolve_pointer(document: JSONObject, fragment: str, *, ref: str) -> Any:
+            target: Any = document
+            for raw_part in fragment[1:].split("/") if fragment.startswith("/") else ():
+                part = raw_part.replace("~1", "/").replace("~0", "~")
+                if not isinstance(target, dict) or part not in target:
+                    raise RuntimeError(f"views schema contains a dangling $ref in {schema_path}: {ref}")
+                target = target[part]
+            return target
+
+        pending: list[tuple[str, JSONObject, Path]] = []
+
+        def add_definition(name: str, source: JSONObject, source_path: Path) -> None:
+            if name in definitions:
+                return
+            source_definitions = source.get("$defs")
+            if not isinstance(source_definitions, dict) or name not in source_definitions:
+                raise RuntimeError(f"views schema references an unknown definition: {name}")
+            definitions[name] = deepcopy(source_definitions[name])
+            pending.append((name, source, source_path))
+
+        def rewrite(value: Any, source: JSONObject, source_path: Path) -> None:
+            if isinstance(value, dict):
+                ref = value.get("$ref")
+                if isinstance(ref, str):
+                    ref_file, _, fragment = ref.partition("#")
+                    target_source = source
+                    target_path = source_path
+                    if ref_file:
+                        target_path = (source_path.parent / ref_file).resolve()
+                        target_name = next(
+                            (name for name, path in paths.items() if path.resolve() == target_path),
+                            None,
+                        )
+                        if target_name is None:
+                            raise RuntimeError(f"views schema contains an external $ref in {source_path}: {ref}")
+                        target_source = schemas[target_name]
+                        dependencies.add(schema_files[target_name])
+                        value["$ref"] = f"#{fragment}"
+                    local_ref = str(value["$ref"])
+                    if local_ref.startswith("#/$defs/"):
+                        name = local_ref.removeprefix("#/$defs/").split("/", 1)[0]
+                        add_definition(name, target_source, target_path)
+                    else:
+                        resolve_pointer(target_source, fragment, ref=ref)
+                for child in value.values():
+                    rewrite(child, source, source_path)
+            elif isinstance(value, list):
+                for child in value:
+                    rewrite(child, source, source_path)
+
+        for key, value in bundled.items():
+            if key != "$defs":
+                rewrite(value, schema, schema_path)
+        while pending:
+            name, source, source_path = pending.pop()
+            rewrite(definitions[name], source, source_path)
+        if definitions:
+            bundled["$defs"] = definitions
+        return bundled, sorted(dependencies)
+
+    def resolve_schema_version(self, schema_version: str | None) -> ViewsSchemaContext:
+        version = str(schema_version or self.latest_version).strip()
+        if version not in self.stored_versions:
+            raise self._version_error("UNSUPPORTED_SCHEMA_VERSION", version)
+        if version not in self.enabled_versions:
+            raise self._version_error("SCHEMA_VERSION_DISABLED", version)
+        return self._contexts[version]
+
+    def resolve_api_version(self, api_version: str) -> ViewsSchemaContext:
+        version = self._api_to_version.get(api_version)
+        if version is not None:
+            return self._contexts[version]
+        stored = self._stored_api_to_version.get(api_version)
+        if stored is not None:
+            raise self._version_error("SCHEMA_VERSION_DISABLED", stored)
+        raise self._version_error("UNSUPPORTED_SCHEMA_VERSION", api_version)
+
+    def _version_error(self, error_code: str, requested: str) -> ViewsContractError:
+        return ViewsContractError(
+            error_code,
+            f"unsupported views schema selection: {requested}",
+            details={
+                "requestedVersion": requested,
+                "latestVersion": self.latest_version,
+                "storedVersions": list(self.stored_versions),
+                "enabledVersions": list(self.enabled_versions),
+            },
+        )
+
+    @staticmethod
+    def _read_json(path: Path) -> JSONObject:
+        value = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(value, dict):
+            raise RuntimeError(f"views schema artifact must be an object: {path}")
+        return value
+
+    @staticmethod
+    def _validate_local_refs(
+        document: JSONObject,
+        path: Path,
+        documents: dict[str, JSONObject],
+        paths: dict[str, Path],
+    ) -> None:
+        stack: list[Any] = [document]
+        while stack:
+            value = stack.pop()
+            if isinstance(value, dict):
+                ref = value.get("$ref")
+                if ref is not None:
+                    if not isinstance(ref, str):
+                        raise RuntimeError(f"views schema contains an invalid $ref in {path}: {ref}")
+                    ref_file, _, fragment = ref.partition("#")
+                    target_document = document
+                    if ref_file:
+                        target_path = (path.parent / ref_file).resolve()
+                        if target_path not in {item.resolve() for item in paths.values()}:
+                            raise RuntimeError(f"views schema contains an external $ref in {path}: {ref}")
+                        target_name = next(name for name, item in paths.items() if item.resolve() == target_path)
+                        target_document = documents[target_name]
+                    target: Any = target_document
+                    for raw_part in fragment[1:].split("/") if fragment.startswith("/") else ():
+                        part = raw_part.replace("~1", "/").replace("~0", "~")
+                        if not isinstance(target, dict) or part not in target:
+                            raise RuntimeError(f"views schema contains a dangling $ref in {path}: {ref}")
+                        target = target[part]
+                stack.extend(value.values())
+            elif isinstance(value, list):
+                stack.extend(value)
+
+    @staticmethod
+    def _configured_versions() -> tuple[str, ...]:
+        raw = os.environ.get("QINGFLOW_VIEWS_SCHEMA_VERSIONS", "")
+        return tuple(part.strip() for part in raw.split(",") if part.strip())
+
+
+_REGISTRY: ViewsSchemaRegistry | None = None
+
+
+def views_schema_registry() -> ViewsSchemaRegistry:
+    global _REGISTRY
+    if _REGISTRY is None:
+        _REGISTRY = ViewsSchemaRegistry()
+    return _REGISTRY

package/src/qingflow_mcp/cli/commands/__init__.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import argparse
 
-from . import app, auth, builder, chart, exports, imports, portal, record, task, view, workspace
+from . import app, auth, builder, chart, data, exports, imports, portal, record, task, view, workspace
 
 
 def register_all_commands(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
@@ -13,6 +13,7 @@ def register_all_commands(subparsers: argparse._SubParsersAction[argparse.Argume
     view.register(subparsers)
     chart.register(subparsers)
     record.register(subparsers)
+    data.register(subparsers)
     imports.register(subparsers)
     exports.register(subparsers)
     task.register(subparsers)

package/src/qingflow_mcp/cli/commands/builder.py

@@ -4,24 +4,30 @@ import argparse
 from copy import deepcopy
 from pathlib import Path
 
-from ..context import CliContext
 from ...app_form_validator import (
     AppFormValidationError,
     build_encoded_id_map,
-    referenced_formula_field_ids,
-    translate_formula_test_case_values,
     encode_code_block_field_ids,
     referenced_code_block_field_ids,
+    referenced_formula_field_ids,
     restore_decimal_ids_in_text,
     strip_placeholder_quotes,
+    translate_formula_test_case_values,
     translate_select_test_case_values,
     validate_code_block_static,
     validate_declaration,
     validate_formula_expression,
 )
+from ...builder_facade.views_schema import VIEWS_SUPPORTED_SCHEMA_KINDS
+from ..context import CliContext
 from ..json_io import load_json_value
-from .common import load_list_arg, load_object_arg, parse_bool_text, raise_config_error, require_list_arg
-
+from .common import (
+    load_list_arg,
+    load_object_arg,
+    parse_bool_text,
+    raise_config_error,
+    require_list_arg,
+)
 
 def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
     parser = subparsers.add_parser("builder", aliases=["build"], help="稳定 builder 命令")
@@ -219,6 +225,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     button_get.add_argument("--app-key", default="")
     button_get.add_argument("--app-keys", default="", help="逗号分隔的多应用 app_key；用于批量读取按钮配置")
     button_get.add_argument("--app-keys-file", help="JSON 字符串数组；用于批量读取按钮配置")
+    button_get.add_argument("--button-text", default="", help="按按钮文案精确查重；命中复用其 button_id，未命中再创建")
     button_get.set_defaults(handler=_handle_button_get, format_hint="builder_summary")
 
     button_apply = button_subparsers.add_parser("apply", help="声明式创建、更新或删除自定义按钮")
@@ -282,14 +289,32 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
 
     views_apply = builder_subparsers.add_parser("views", help="视图")
     views_apply_subparsers = views_apply.add_subparsers(dest="builder_views_command", required=True)
+    views_schema = views_apply_subparsers.add_parser("schema", help="读取视图声明 Schema")
+    views_schema.add_argument("--schema-version")
+    views_schema.add_argument(
+        "--schema-kind",
+        choices=VIEWS_SUPPORTED_SCHEMA_KINDS,
+    )
+    views_schema.set_defaults(handler=_handle_views_schema, format_hint="builder_summary", force_json_output=True)
+
+    views_get = views_apply_subparsers.add_parser("get", help="读取 canonical 视图声明")
+    views_get.add_argument("--app-key", required=True)
+    views_get.add_argument("--schema-version")
+    views_get.add_argument("--schema-kind", choices=("summary", "complete"), help="summary＝投影字段；complete＝逐视图读 viewConfig 反向编译（含覆盖度 gaps）")
+    views_get.set_defaults(handler=_handle_views_get, format_hint="builder_summary", force_json_output=True)
+
+    views_validate = views_apply_subparsers.add_parser("validate", help="只校验视图声明，不访问后端")
+    views_validate.add_argument("--file", required=True, help="视图声明 JSON 文件，- 表示 stdin")
+    views_validate.add_argument("--schema-version", help="固定使用的视图 Schema 版本；缺省读文件内 schema_version，再缺省 latest")
+    views_validate.set_defaults(handler=_handle_views_validate, format_hint="builder_summary", force_json_output=True)
+
     views_apply_apply = views_apply_subparsers.add_parser("apply", help="执行视图变更")
-    views_apply_apply.add_argument("--app-key", default="")
-    views_apply_apply.add_argument("--views-file", help='推荐批量视图 JSON 对象：{"views":[...]}；每项包含 app_key、operation、视图配置')
-    views_apply_apply.add_argument("--apps-file", help="多应用视图 JSON 数组；每项包含 app_key 和 upsert/patch/remove payload")
+    views_apply_apply.add_argument("--app-key", required=True)
     views_apply_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=True)
-    views_apply_apply.add_argument("--upsert-views-file")
+    views_apply_apply.add_argument("--view-file", help="单条新建或完整更新视图的 JSON 对象")
     views_apply_apply.add_argument("--patch-views-file")
     views_apply_apply.add_argument("--remove-views-file")
+    views_apply_apply.add_argument("--schema-version", help="声明使用的 Schema 版本；缺省 latest，信封回显 schemaVersion")
     views_apply_apply.set_defaults(handler=_handle_views_apply, format_hint="builder_summary", force_json_output=True)
 
     flow_apply = builder_subparsers.add_parser("flow", help="流程")
@@ -874,12 +899,13 @@ def _handle_associated_resource_apply(args: argparse.Namespace, context: CliCont
 
 
 def _handle_button_get(args: argparse.Namespace, context: CliContext) -> dict:
+    button_text = str(getattr(args, "button_text", "") or "").strip() or None
     app_keys = _app_keys_from_args(args)
     if app_keys is not None:
-        return context.builder.app_get_buttons(profile=args.profile, app_key="", app_keys=app_keys)
+        return context.builder.app_get_buttons(profile=args.profile, app_key="", app_keys=app_keys, button_text=button_text)
     if not (args.app_key or "").strip():
         raise_config_error("builder button get requires --app-key unless --app-keys or --app-keys-file is provided")
-    return context.builder.app_get_buttons(profile=args.profile, app_key=args.app_key)
+    return context.builder.app_get_buttons(profile=args.profile, app_key=args.app_key, button_text=button_text)
 
 
 def _handle_associated_resource_get(args: argparse.Namespace, context: CliContext) -> dict:
@@ -1187,30 +1213,6 @@ def _coerce_apps_file_bool(value: object, *, field_name: str, default: bool) ->
     )
 
 
-def _load_views_file_arg(path: str | None) -> list[object] | None:
-    if not path:
-        return None
-    payload = load_json_value(path, option_name="--views-file")
-    if isinstance(payload, dict):
-        views = payload.get("views")
-        if not isinstance(views, list):
-            raise_config_error(
-                "--views-file JSON object must contain a views array.",
-                fix_hint='Use {"views": [{"operation": "upsert", "app_key": "...", "name": "...", "type": "table", "columns": [...]}]}.',
-                error_code="VIEWS_FILE_SHAPE_INVALID",
-                details={"expected": '{"views": [...]}', "actual_type": type(views).__name__},
-            )
-        return views
-    if isinstance(payload, list):
-        return payload
-    raise_config_error(
-        "--views-file must be a JSON object with views[] or a JSON array.",
-        fix_hint='Prefer {"views": [...]} for new automation. A bare array is accepted only for compatibility.',
-        error_code="VIEWS_FILE_SHAPE_INVALID",
-        details={"actual_type": type(payload).__name__},
-    )
-
-
 def _handle_layout_apply(args: argparse.Namespace, context: CliContext) -> dict:
     apps = load_list_arg(args.apps_file, option_name="--apps-file") if getattr(args, "apps_file", None) else None
     if apps is None and not (args.app_key or "").strip():
@@ -1235,34 +1237,53 @@ def _handle_layout_apply(args: argparse.Namespace, context: CliContext) -> dict:
     )
 
 
+def _handle_views_schema(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_views_schema(
+        schema_version=args.schema_version,
+        schema_kind=args.schema_kind,
+    )
+
+
+def _handle_views_get(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_views_get(
+        profile=args.profile,
+        app_key=args.app_key,
+        schema_version=args.schema_version,
+        schema_kind=getattr(args, "schema_kind", None) or "summary",
+    )
+
+
+def _handle_views_validate(args: argparse.Namespace, context: CliContext) -> dict:
+    payload = load_json_value(
+        args.file,
+        option_name="--file",
+        max_bytes=2 * 1024 * 1024,
+        max_depth=64,
+    )
+    if not isinstance(payload, dict):
+        raise_config_error("builder views validate --file must contain a JSON object")
+    return context.builder.app_views_validate(
+        declaration=payload,
+        schema_version=args.schema_version,
+    )
+
+
 def _handle_views_apply(args: argparse.Namespace, context: CliContext) -> dict:
-    views = _load_views_file_arg(args.views_file) if getattr(args, "views_file", None) else None
-    apps = load_list_arg(args.apps_file, option_name="--apps-file") if getattr(args, "apps_file", None) else None
-    if views is not None:
-        if apps is not None or (args.app_key or "").strip() or getattr(args, "upsert_views_file", None) or getattr(args, "patch_views_file", None) or getattr(args, "remove_views_file", None):
-            raise_config_error(
-                "builder views apply --views-file cannot be mixed with --app-key, --apps-file, --upsert-views-file, --patch-views-file, or --remove-views-file.",
-                fix_hint="Use one shape: preferred --views-file for flat batch jobs, or legacy --app-key/--apps-file for grouped payloads.",
-            )
-        return context.builder.app_views_apply(
-            profile=args.profile,
-            app_key="",
-            publish=bool(args.publish),
-            upsert_views=[],
-            patch_views=[],
-            remove_views=[],
-            views=views,
+    view = load_object_arg(args.view_file, option_name="--view-file") if getattr(args, "view_file", None) else None
+    if view is None and not (getattr(args, "patch_views_file", None) or getattr(args, "remove_views_file", None)):
+        raise_config_error(
+            "builder views apply requires --view-file, --patch-views-file, or --remove-views-file.",
+            fix_hint="Pass one JSON object through --view-file to create or fully update one view.",
+            error_code="ARGUMENT_ERROR",
         )
-    if apps is None and not (args.app_key or "").strip():
-        raise_config_error("builder views apply requires --views-file, --apps-file, or --app-key")
     return context.builder.app_views_apply(
         profile=args.profile,
         app_key=args.app_key,
         publish=bool(args.publish),
-        upsert_views=load_list_arg(args.upsert_views_file, option_name="--upsert-views-file"),
+        upsert_view=view,
         patch_views=load_list_arg(args.patch_views_file, option_name="--patch-views-file"),
         remove_views=load_list_arg(args.remove_views_file, option_name="--remove-views-file"),
-        apps=apps,
+        schema_version=getattr(args, "schema_version", None),
     )