@qingflow-tech/qingflow-cli 1.1.41 → 1.1.43-beta.1

package/src/qingflow_mcp/builder_facade/app_form_schema.py

@@ -0,0 +1,269 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from jsonschema import Draft202012Validator, FormatChecker
+
+
+JSONObject = dict[str, Any]
+SCHEMA_ROOT = Path(__file__).with_name("schemas") / "app_form"
+
+
+class AppFormContractError(ValueError):
+    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 {}
+
+
+@dataclass(frozen=True, slots=True)
+class AppFormSchemaContext:
+    schema_version: str
+    api_version: str
+    complete_schema: JSONObject
+    supported_types: tuple[str, ...]
+    contract_source: str
+    contract_version: str
+    normalizer_version: str
+    apply_dto: type[AppFormApplyDTO]
+
+    def validate(self, payload: JSONObject) -> None:
+        validator = Draft202012Validator(self.complete_schema, format_checker=FormatChecker())
+        errors = sorted(validator.iter_errors(payload), key=lambda item: (list(item.absolute_path), item.message))
+        if not errors:
+            return
+        error = errors[0]
+        pointer = "".join(f"/{str(part).replace('~', '~0').replace('/', '~1')}" for part in error.absolute_path) or "/"
+        raise AppFormContractError(
+            "INVALID_SPEC",
+            error.message,
+            path=pointer,
+            details={"validator": error.validator, "schemaPath": "/".join(str(part) for part in error.absolute_schema_path)},
+        )
+
+    def parse_apply(self, payload: JSONObject) -> AppFormApplyDTO:
+        self.validate(payload)
+        return self.apply_dto(
+            contract_source=self.contract_source,
+            contract_version=self.contract_version,
+            normalizer_version=self.normalizer_version,
+            resource=deepcopy(payload),
+        )
+
+    def assert_apply_dto(self, value: AppFormApplyDTO) -> None:
+        if not isinstance(value, self.apply_dto):
+            raise AppFormContractError(
+                "SCHEMA_VERSION_MISMATCH",
+                "AppForm declaration was parsed by a different DTO type",
+                details={"expected": self.apply_dto.__name__, "actual": type(value).__name__},
+            )
+        actual = (value.contract_source, value.contract_version, value.normalizer_version)
+        expected = (self.contract_source, self.contract_version, self.normalizer_version)
+        if actual != expected:
+            raise AppFormContractError(
+                "SCHEMA_VERSION_MISMATCH",
+                "AppForm declaration was parsed by a different contract version",
+                details={"expected": expected, "actual": actual},
+            )
+
+
+@dataclass(frozen=True, slots=True)
+class AppFormApplyDTO:
+    contract_source: str
+    contract_version: str
+    normalizer_version: str
+    resource: JSONObject
+
+
+@dataclass(frozen=True, slots=True)
+class AppFormV1Alpha1ApplyDTO(AppFormApplyDTO):
+    pass
+
+
+APPLY_DTO_TYPES: dict[str, type[AppFormApplyDTO]] = {
+    "v1alpha1": AppFormV1Alpha1ApplyDTO,
+}
+
+
+class AppFormSchemaRegistry:
+    def __init__(self, root: Path = 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("AppForm schema manifest must define versions")
+        configured = enabled_versions or self._configured_versions()
+        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"AppForm schema metadata must be an object: {version}")
+            api_version = str(metadata.get("apiVersion") or "")
+            if not api_version:
+                raise RuntimeError(f"AppForm schema version has no apiVersion: {version}")
+            if api_version in self._stored_api_to_version:
+                raise RuntimeError(f"duplicate AppForm apiVersion: {api_version}")
+            self._stored_api_to_version[api_version] = str(version)
+        defaults = tuple(
+            str(version)
+            for version, metadata in versions.items()
+            if isinstance(metadata, dict) and bool(metadata.get("enabledByDefault"))
+        )
+        self.enabled_versions = configured or defaults
+        if self.latest_version not in versions:
+            raise RuntimeError("AppForm latestVersion is not stored")
+        if self.latest_version not in self.enabled_versions:
+            raise RuntimeError("AppForm latestVersion must remain enabled")
+        self._contexts: dict[str, AppFormSchemaContext] = {}
+        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 AppForm schema version is not stored: {version}")
+            api_version = str(metadata.get("apiVersion") or "")
+            complete = self._read_json(root / version / "complete.json")
+            supported = tuple(str(item) for item in metadata.get("fieldTypes") or ())
+            if complete.get("properties", {}).get("apiVersion", {}).get("const") != api_version:
+                raise RuntimeError(f"AppForm schema apiVersion mismatch for {version}")
+            schema_id = str(complete.get("$id") or "")
+            if version not in schema_id:
+                raise RuntimeError(f"AppForm schema $id mismatch for {version}")
+            Draft202012Validator.check_schema(complete)
+            self._validate_local_refs(complete, root / version / "complete.json")
+            summary = self._read_json(root / version / "summary.json")
+            if summary.get("properties", {}).get("apiVersion", {}).get("const") != api_version:
+                raise RuntimeError(f"AppForm summary apiVersion mismatch for {version}")
+            Draft202012Validator.check_schema(summary)
+            self._validate_local_refs(summary, root / version / "summary.json")
+            for field_type in supported:
+                field_path = root / version / "fields" / f"{field_type}.json"
+                field_schema = self._read_json(field_path)
+                Draft202012Validator.check_schema(field_schema)
+                self._validate_local_refs(field_schema, field_path)
+            context = AppFormSchemaContext(
+                version,
+                api_version,
+                complete,
+                supported,
+                str(metadata.get("contractSource") or "app_form"),
+                str(metadata.get("contractVersion") or version),
+                str(metadata.get("normalizerVersion") or version),
+                self._apply_dto_type(version, metadata),
+            )
+            self._contexts[version] = context
+            self._api_to_version[api_version] = version
+
+    def schema(self, *, schema_version: str | None = None, field_type: str | None = None) -> JSONObject:
+        context = self.resolve_schema_version(schema_version)
+        if field_type is None:
+            schema = self._read_json(self.root / context.schema_version / "summary.json")
+            schema_kind = "summary"
+        else:
+            if field_type not in context.supported_types:
+                raise AppFormContractError(
+                    "UNSUPPORTED_SCHEMA_FIELD_TYPE",
+                    f"unsupported AppForm field type: {field_type}",
+                    details={"supportedTypes": list(context.supported_types)},
+                )
+            schema = self._read_json(self.root / context.schema_version / "fields" / f"{field_type}.json")
+            schema_kind = "field"
+        return {
+            "schemaVersion": context.schema_version,
+            "apiVersion": context.api_version,
+            "latestVersion": self.latest_version,
+            "storedVersions": list(self.stored_versions),
+            "enabledVersions": list(self.enabled_versions),
+            "schemaKind": schema_kind,
+            "fieldType": field_type,
+            "schema": schema,
+        }
+
+    def resolve_schema_version(self, schema_version: str | None) -> AppFormSchemaContext:
+        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._resolved_context(version)
+
+    def resolve_api_version(self, api_version: str) -> AppFormSchemaContext:
+        version = self._api_to_version.get(api_version)
+        if version is not None:
+            return self._resolved_context(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 _resolved_context(self, version: str) -> AppFormSchemaContext:
+        return self._contexts[version]
+
+    @staticmethod
+    def _apply_dto_type(version: str, metadata: JSONObject) -> type[AppFormApplyDTO]:
+        dto_name = str(metadata.get("applyDto") or version)
+        dto_type = APPLY_DTO_TYPES.get(dto_name)
+        if dto_type is None:
+            raise RuntimeError(f"AppForm schema version {version} references unknown apply DTO: {dto_name}")
+        return dto_type
+
+    def _version_error(self, error_code: str, requested: str) -> AppFormContractError:
+        return AppFormContractError(
+            error_code,
+            f"unsupported AppForm 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"AppForm schema artifact must be an object: {path}")
+        return value
+
+    @staticmethod
+    def _validate_local_refs(document: JSONObject, path: 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) or (ref != "#" and not ref.startswith("#/")):
+                        raise RuntimeError(f"AppForm schema contains an external or invalid $ref in {path}: {ref}")
+                    target: Any = document
+                    for raw_part in ref[2:].split("/") if ref.startswith("#/") else ():
+                        part = raw_part.replace("~1", "/").replace("~0", "~")
+                        if not isinstance(target, dict) or part not in target:
+                            raise RuntimeError(f"AppForm 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_APP_FORM_SCHEMA_VERSIONS", "")
+        return tuple(part.strip() for part in raw.split(",") if part.strip())
+
+
+_REGISTRY: AppFormSchemaRegistry | None = None
+
+
+def app_form_schema_registry() -> AppFormSchemaRegistry:
+    global _REGISTRY
+    if _REGISTRY is None:
+        _REGISTRY = AppFormSchemaRegistry()
+    return _REGISTRY

package/src/qingflow_mcp/builder_facade/schemas/app_form/manifest.json

@@ -0,0 +1,37 @@
+{
+  "latestVersion": "v1alpha1",
+  "versions": {
+    "v1alpha1": {
+      "apiVersion": "builder.qingflow.com/v1alpha1",
+      "applyDto": "v1alpha1",
+      "contractSource": "app_form",
+      "contractVersion": "v1alpha1",
+      "enabledByDefault": true,
+      "fieldTypes": [
+        "text",
+        "long_text",
+        "number",
+        "amount",
+        "link",
+        "date",
+        "datetime",
+        "member",
+        "department",
+        "single_choice",
+        "single_select",
+        "multi_select",
+        "phone",
+        "email",
+        "address",
+        "attachment",
+        "q_linker",
+        "code_block",
+        "data_relation",
+        "relation",
+        "subtable"
+      ],
+      "normalizerVersion": "v1alpha1",
+      "status": "active"
+    }
+  }
+}