@qingflow-tech/qingflow-cli 1.1.50-beta.5 → 1.1.51

package/src/qingflow_mcp/builder_facade/views_schema.py

@@ -1,400 +0,0 @@
-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/data.py

@@ -1,134 +0,0 @@
-from __future__ import annotations
-
-import argparse
-import textwrap
-
-from ..context import CliContext
-from .common import load_list_arg, require_list_arg, require_object_arg, raise_config_error
-
-
-def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
-    parser = subparsers.add_parser(
-        "data",
-        help="默认应用数据查询与直接增删改",
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog=textwrap.dedent("""
-            JSON 文件约定：
-              columns.json  [101, 102]
-              where.json    [{"field_id": 101, "op": "eq", "value": "A"}]
-              sort.json     [{"field_id": 101, "direction": "asc"}]
-              items.json    [{"fields": {"101": "A"}}]
-              fields.json   {"101": "B"}
-            query/get/insert/update 默认返回 field_capabilities；可用 --no-schema 关闭。
-        """).strip(),
-    )
-    commands = parser.add_subparsers(dest="data_command", required=True, metavar="{query,get,insert,update,delete}")
-
-    query = commands.add_parser(
-        "query", help="分页查询应用数据", formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog='最小示例：qingflow data query --app-key APP_1 --where-file where.json\n'
-               'where.json: [{"field_id": 101, "op": "eq", "value": "A"}]',
-    )
-    query.add_argument("--app-key", required=True)
-    query.add_argument("--columns-file", help='JSON 数组，例如 [101, 102]')
-    query.add_argument(
-        "--where-file",
-        help='JSON 数组；项为 {"field_id":101,"op":"eq","value":"A"}，in/not_in 的 value 必须为数组',
-    )
-    query.add_argument("--sort-file", help='JSON 数组，例如 [{"field_id":101,"direction":"asc"}]')
-    query.add_argument("--search", default="")
-    query.add_argument("--page", type=int, default=1)
-    query.add_argument("--page-size", type=int, default=100)
-    query.add_argument("--no-schema", action="store_false", dest="include_schema", default=True)
-    query.add_argument("--all", action="store_true", dest="all_pages")
-    query.add_argument("--output", choices=("json", "csv"), default="json")
-    query.set_defaults(handler=_handle_query, format_hint="data_query")
-
-    get = commands.add_parser("get", help="读取单条应用数据")
-    get.add_argument("--app-key", required=True)
-    get.add_argument("--record-id", required=True)
-    get.add_argument("--no-schema", action="store_false", dest="include_schema", default=True)
-    get.set_defaults(handler=_handle_get, format_hint="data_get")
-
-    insert = commands.add_parser(
-        "insert", help="新增应用数据", formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog='最小示例：items.json = [{"fields": {"101": "A"}}]',
-    )
-    insert.add_argument("--app-key", required=True)
-    insert.add_argument("--items-file", required=True, help='JSON 数组，项为 {"fields":{"字段ID":值}}')
-    insert.add_argument("--no-schema", action="store_false", dest="include_schema", default=True)
-    insert.set_defaults(handler=_handle_insert, format_hint="data_insert")
-
-    update = commands.add_parser(
-        "update", help="更新应用数据", formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog='最小示例：fields.json = {"101": "B"}',
-    )
-    update.add_argument("--app-key", required=True)
-    update.add_argument("--record-id", required=True)
-    update.add_argument("--fields-file", required=True, help='JSON 对象，键为字符串形式 field_id')
-    update.add_argument("--no-schema", action="store_false", dest="include_schema", default=True)
-    update.set_defaults(handler=_handle_update, format_hint="data_update")
-
-    delete = commands.add_parser("delete", help="删除应用数据")
-    delete.add_argument("--app-key", required=True)
-    delete.add_argument(
-        "--record-ids", action="append", default=[], metavar="ID[,ID...]",
-        help="待删除记录 ID；支持逗号分隔，也可重复传入",
-    )
-    delete.add_argument("--record-ids-file", help="附加的记录 ID JSON 数组文件")
-    delete.set_defaults(handler=_handle_delete, format_hint="data_delete")
-
-
-def _handle_query(args: argparse.Namespace, context: CliContext) -> dict:
-    if args.all_pages != (args.output == "csv"):
-        raise_config_error(
-            "--all 与 --output csv 必须同时使用。",
-            fix_hint="使用 `qingflow data query ... --all --output csv`，普通分页查询不要传这两个参数。",
-        )
-    return context.data.data_query(
-        profile=args.profile,
-        app_key=args.app_key,
-        columns=load_list_arg(args.columns_file, option_name="--columns-file"),
-        where=load_list_arg(args.where_file, option_name="--where-file"),
-        sort=load_list_arg(args.sort_file, option_name="--sort-file"),
-        search=args.search,
-        page=args.page,
-        page_size=args.page_size,
-        include_schema=args.include_schema,
-        all_pages=args.all_pages,
-        output=args.output,
-    )
-
-
-def _handle_get(args: argparse.Namespace, context: CliContext) -> dict:
-    return context.data.data_get(
-        profile=args.profile, app_key=args.app_key, record_id=args.record_id, include_schema=args.include_schema
-    )
-
-
-def _handle_insert(args: argparse.Namespace, context: CliContext) -> dict:
-    return context.data.data_insert(
-        profile=args.profile, app_key=args.app_key,
-        items=require_list_arg(args.items_file, option_name="--items-file"), include_schema=args.include_schema,
-    )
-
-
-def _handle_update(args: argparse.Namespace, context: CliContext) -> dict:
-    return context.data.data_update(
-        profile=args.profile, app_key=args.app_key, record_id=args.record_id,
-        fields=require_object_arg(args.fields_file, option_name="--fields-file"), include_schema=args.include_schema,
-    )
-
-
-def _handle_delete(args: argparse.Namespace, context: CliContext) -> dict:
-    record_ids = [item.strip() for group in args.record_ids for item in group.split(",") if item.strip()]
-    record_ids.extend(load_list_arg(args.record_ids_file, option_name="--record-ids-file"))
-    if not record_ids:
-        raise_config_error(
-            "至少传入一个记录 ID。",
-            fix_hint="使用 `--record-ids ID[,ID...]`；也可附加 `--record-ids-file ids.json`。",
-        )
-    return context.data.data_delete(
-        profile=args.profile, app_key=args.app_key,
-        record_ids=record_ids,
-    )