hap-cli 0.7.1__tar.gz → 0.7.2__tar.gz

{hap_cli-0.7.1 → hap_cli-0.7.2}/MANIFEST.in

@@ -11,3 +11,8 @@ include sources/v3-api-schema/INDEX.json
 include hap_cli/README.md
 include hap_cli/README_CN.md
 recursive-include hap_cli/locale *.json
+
+# edit-spec schemas are canonical in the hap-cli-app-editor skill; ship them
+# in the sdist so setup.py's build step can mirror them into
+# hap_cli/core/editor/editspec/ for the ``hap app-editor`` runtime loader.
+recursive-include skills/hap-cli-app-editor/scripts/editspec *.json

{hap_cli-0.7.1 → hap_cli-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hap-cli
-Version: 0.7.1
+Version: 0.7.2
 Summary: CLI harness for MingDAO HAP - Enterprise no-code platform
 Author: hap-cli
 License: Apache-2.0

{hap_cli-0.7.1 → hap_cli-0.7.2}/app_live_tests/harness.py

@@ -53,11 +53,14 @@ def hap(args: list[str], *, check: bool = True) -> Any:
 
 
 def editor(args: list[str]) -> tuple[int, str, str]:
-    """Run the editor skill (``python -m scripts <args>``) in the skill dir."""
-    py = config.PYTHON_BIN or sys.executable
-    argv = [py, "-m", "scripts", *args]
+    """Run the editor via the installed CLI: ``hap app-editor <args>``.
+
+    The editor engine was migrated into hap-cli, so the entry point is now
+    the real command (not ``python -m scripts``).
+    """
+    argv = [config.HAP_BIN, "app-editor", *args]
     proc = subprocess.run(argv, capture_output=True, text=True,
-                          cwd=str(config.SKILL_DIR), timeout=config.TIMEOUT)
+                          timeout=config.TIMEOUT)
     return proc.returncode, proc.stdout, proc.stderr
 
 

{hap_cli-0.7.1 → hap_cli-0.7.2}/hap_cli/__init__.py

@@ -1,3 +1,3 @@
 """CLI harness for MingDAO HAP (hap-cli)."""
 
-__version__ = "0.7.1"
+__version__ = "0.7.2"

hap_cli-0.7.2/hap_cli/commands/app_editor_cmd.py

@@ -0,0 +1,137 @@
+"""CLI commands for fine-grained HAP app element editing (``hap app-editor``).
+
+Thin Click layer over the editor engine in ``hap_cli.core.editor``:
+edit-spec validation, live inspection, dry-run planning, and applying
+single-element changes (worksheet / field / view / role / custom-action /
+workflow / custom-page / component / chatbot / node / app / section).
+
+The edit-spec schemas are documented and shipped with the
+``hap-cli-app-editor`` skill; this command resolves them at runtime.
+"""
+import json
+
+import click
+
+from hap_cli.context import pass_context
+from hap_cli.core.editor import apply as apply_mod
+from hap_cli.core.editor import editspec, planner
+from hap_cli.core.editor.errors import EditorError, EditSpecError
+from hap_cli.core.editor.reader import AppIndex
+from hap_cli.utils.options import org_id_option
+
+
+@click.group("app-editor", help="Fine-grained edit of an existing HAP app's "
+                                "elements via a structured edit-spec.")
+def app_editor():
+    pass
+
+
+@app_editor.command("validate")
+@click.argument("spec_path", type=click.Path(exists=True, dir_okay=False))
+@pass_context
+def app_editor_validate(ctx, spec_path):
+    """Validate an edit-spec locally (no API calls)."""
+    try:
+        editspec.load_spec(spec_path)
+    except EditSpecError as exc:
+        if ctx.json_mode:
+            ctx.output({"valid": False, "problems": exc.problems})
+        else:
+            click.echo("edit-spec invalid:", err=True)
+            for p in exc.problems:
+                click.echo(f"  - {p}", err=True)
+        raise SystemExit(2)
+    ctx.output({"valid": True}, lambda d: click.echo("edit-spec OK"))
+
+
+def _resolve_app_ref(spec, app_override):
+    return app_override or spec.get("app")
+
+
+@app_editor.command("inspect")
+@click.argument("app_ref")
+@org_id_option()
+@pass_context
+def app_editor_inspect(ctx, app_ref, org_id):
+    """Print the live name->id structure of an app (worksheets, views,
+    roles, workflows, pages, ...) — author edit-specs against it."""
+    try:
+        session = ctx.get_session()
+        idx = AppIndex.load(session, app_ref, org_id)
+        ctx.output(idx.summary(),
+                   lambda d: click.echo(json.dumps(d, ensure_ascii=False, indent=2)))
+    except EditorError as e:
+        ctx.handle_error(e)
+    except Exception as e:  # noqa: BLE001
+        ctx.handle_error(e)
+
+
+@app_editor.command("plan")
+@click.argument("spec_path", type=click.Path(exists=True, dir_okay=False))
+@click.option("--app", "app_override", default="",
+              help="Override the spec's target app (id or name).")
+@org_id_option()
+@pass_context
+def app_editor_plan(ctx, spec_path, app_override, org_id):
+    """Dry run: validate, read live structure, and show what apply would do."""
+    try:
+        spec = editspec.load_spec(spec_path)
+        session = ctx.get_session()
+        idx = AppIndex.load(session, _resolve_app_ref(spec, app_override), org_id)
+        planned = planner.build_plan(spec, idx)
+        ctx.output(
+            {"ops": [{"index": p.index, "type": p.op.get("type"),
+                      "actions": [a.description for a in p.actions]}
+                     for p in planned]},
+            lambda d: click.echo(planner.render_plan(planned)))
+    except EditSpecError as exc:
+        for p in exc.problems:
+            click.echo(f"  - {p}", err=True)
+        raise SystemExit(2)
+    except Exception as e:  # noqa: BLE001
+        ctx.handle_error(e)
+
+
+@app_editor.command("apply")
+@click.argument("spec_path", type=click.Path(exists=True, dir_okay=False))
+@click.option("--app", "app_override", default="",
+              help="Override the spec's target app (id or name).")
+@org_id_option()
+@click.option("--continue", "cont", is_flag=True, default=False,
+              help="Keep going after an op fails (default: stop).")
+@pass_context
+def app_editor_apply(ctx, spec_path, app_override, org_id, cont):
+    """Apply an edit-spec against the live app, op by op."""
+    try:
+        spec = editspec.load_spec(spec_path)
+        session = ctx.get_session()
+        idx = AppIndex.load(session, _resolve_app_ref(spec, app_override), org_id)
+
+        def _echo(outcome):
+            if not ctx.json_mode:
+                mark = "OK " if outcome.status == "ok" else "ERR"
+                tail = f" — {outcome.detail}" if outcome.detail else ""
+                click.echo(f"  [{mark}] [{outcome.index}] {outcome.op_type}{tail}")
+
+        outcomes = apply_mod.apply_spec(spec, idx, continue_on_error=cont,
+                                        on_outcome=_echo)
+        errors = [o for o in outcomes if o.status == "error"]
+        ctx.output(
+            {"applied": len(outcomes) - len(errors), "total": len(outcomes),
+             "failed": len(errors),
+             "outcomes": [{"index": o.index, "type": o.op_type,
+                           "status": o.status, "detail": o.detail}
+                          for o in outcomes]},
+            lambda d: click.echo(
+                f"applied {d['applied']}/{d['total']} ops"
+                + (f", {d['failed']} failed" if d['failed'] else "")))
+        if errors:
+            raise SystemExit(1)
+    except EditSpecError as exc:
+        for p in exc.problems:
+            click.echo(f"  - {p}", err=True)
+        raise SystemExit(2)
+    except SystemExit:
+        raise
+    except Exception as e:  # noqa: BLE001
+        ctx.handle_error(e)

hap_cli-0.7.2/hap_cli/core/editor/__init__.py

@@ -0,0 +1,12 @@
+"""Fine-grained HAP app element editor — engine for ``hap app-editor``.
+
+Migrated from the standalone ``hap-cli-app-editor`` skill so the logic
+lives once in hap-cli and is shared as a CLI command. Unlike the old
+skill (which shelled out to the ``hap`` binary), this calls
+``hap_cli.core.*`` directly — no subprocess, and API errors surface as
+exceptions.
+
+The edit-spec schemas remain canonical in the skill
+(``skills/hap-cli-app-editor/scripts/editspec/``); :mod:`editspec`
+resolves them at runtime (repo layout) or from the wheel-bundled copy.
+"""

hap_cli-0.7.2/hap_cli/core/editor/_hapmeta/__init__.py

@@ -0,0 +1,5 @@
+"""Self-contained HAP metadata (field type codes, ...) for the editor.
+
+Copied into this skill so it is independently distributable — it does not
+import hap_cli or the hap-cli-app-creator skill.
+"""

hap_cli-0.7.2/hap_cli/core/editor/_hapmeta/control_type_codes.py

@@ -0,0 +1,58 @@
+"""HAP field (control) type codes — name <-> numeric type id.
+
+Authoritative source: ``hap worksheet field-types``. This is a baked
+copy so the skill ships self-contained; refresh it from that command if
+HAP adds types. ``resolve(t)`` accepts a friendly code ("Text"), a
+legacy name ("TEXT"), or an int / numeric string and returns the int.
+"""
+from __future__ import annotations
+
+# code -> numeric type id. Region has variants (19 county / 23 / 24);
+# default to 19, override with an explicit int when needed.
+CODE_TO_ID: dict[str, int] = {
+    "Text": 2, "PhoneNumber": 3, "LandlinePhone": 4, "Email": 5,
+    "Number": 6, "Certificate": 7, "Currency": 8, "SingleSelect": 9,
+    "MultipleSelect": 10, "Dropdown": 11, "Attachment": 14, "Date": 15,
+    "DateTime": 16, "Region": 19, "DynamicLink": 21, "Divider": 22,
+    "AmountInWords": 25, "Collaborator": 26, "Department": 27, "Rating": 28,
+    "Relation": 29, "Lookup": 30, "Formula": 31, "Concatenate": 32,
+    "AutoNumber": 33, "SubTable": 34, "CascadingSelect": 35, "Checkbox": 36,
+    "Rollup": 37, "DateFormula": 38, "CodeScan": 39, "Location": 40,
+    "RichText": 41, "Signature": 42, "OCR": 43, "Role": 44, "Embed": 45,
+    "Time": 46, "Barcode": 47, "OrgRole": 48, "Button": 49, "APIQuery": 50,
+    "QueryRecord": 51, "Section": 52, "FunctionFormula": 53, "CustomField": 54,
+}
+
+# legacy builder name -> numeric type id (accepted as an alias).
+LEGACY_TO_ID: dict[str, int] = {
+    "TEXT": 2, "MOBILE_PHONE": 3, "TELEPHONE": 4, "EMAIL": 5, "NUMBER": 6,
+    "CRED": 7, "MONEY": 8, "FLAT_MENU": 9, "MULTI_SELECT": 10, "DROP_DOWN": 11,
+    "ATTACHMENT": 14, "DATE": 15, "DATE_TIME": 16, "AREA_COUNTY": 19,
+    "RELATION": 21, "SPLIT_LINE": 22, "MONEY_CN": 25, "USER_PICKER": 26,
+    "DEPARTMENT": 27, "SCORE": 28, "RELATE_SHEET": 29, "SHEET_FIELD": 30,
+    "FORMULA_NUMBER": 31, "CONCATENATE": 32, "AUTO_ID": 33, "SUB_LIST": 34,
+    "CASCADER": 35, "SWITCH": 36, "SUBTOTAL": 37, "FORMULA_DATE": 38,
+    "LOCATION": 40, "RICH_TEXT": 41, "SIGNATURE": 42, "OCR": 43, "EMBED": 45,
+    "TIME": 46, "BAR_CODE": 47, "ORG_ROLE": 48, "SEARCH_BTN": 49,
+    "SEARCH": 50, "RELATION_SEARCH": 51, "SECTION": 52, "FORMULA_FUNC": 53,
+    "CUSTOM": 54,
+}
+
+# Type ids that hold a select-style ``options`` list.
+SELECT_TYPE_IDS = {9, 10, 11}
+
+
+def resolve(t) -> int:
+    """Return the numeric type id for a code / legacy name / int."""
+    if isinstance(t, bool):
+        raise ValueError(f"invalid field type: {t!r}")
+    if isinstance(t, int):
+        return t
+    if isinstance(t, str):
+        if t.isdigit():
+            return int(t)
+        if t in CODE_TO_ID:
+            return CODE_TO_ID[t]
+        if t in LEGACY_TO_ID:
+            return LEGACY_TO_ID[t]
+    raise ValueError(f"unknown field type: {t!r}")

hap_cli-0.7.2/hap_cli/core/editor/apply.py

@@ -0,0 +1,51 @@
+"""Execute an edit-spec against the live app (direct core calls)."""
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+from hap_cli.core.editor import ops as ops_mod
+from hap_cli.core.editor.errors import EditorError
+from hap_cli.core.editor.models import OpOutcome
+from hap_cli.core.editor.planner import check_confirm
+from hap_cli.core.editor.reader import AppIndex
+
+
+def apply_spec(
+    spec: dict,
+    idx: AppIndex,
+    *,
+    continue_on_error: bool = False,
+    on_outcome: Optional[Callable[[OpOutcome], None]] = None,
+) -> list[OpOutcome]:
+    """Apply every op against ``idx``'s app. Returns outcomes.
+
+    Actions are built op-by-op against a freshly-refreshed index so an op
+    can reference an element a previous op just created (intra-spec
+    chaining). The confirm gate is enforced up front before anything runs.
+    Each Action's ``call`` performs the mutation via ``hap_cli.core.*``;
+    any error (API or resolution) is captured as an error outcome.
+    """
+    ops = spec.get("ops", [])
+    for op in ops:                       # pre-flight: fail fast on missing confirm
+        check_confirm(op)
+
+    session = idx.session
+    outcomes: list[OpOutcome] = []
+    for i, op in enumerate(ops):
+        op_type = op.get("type", "")
+        responses: list = []
+        try:
+            idx.refresh()                # see effects of prior ops
+            builder = ops_mod.REGISTRY[op_type]
+            for action in builder(op, idx):
+                responses.append(action.call(session))
+            outcome = OpOutcome(i, op_type, "ok", responses=responses)
+        except (EditorError, Exception) as exc:  # noqa: BLE001 — record + decide
+            outcome = OpOutcome(i, op_type, "error", detail=str(exc),
+                                responses=responses)
+        outcomes.append(outcome)
+        if on_outcome:
+            on_outcome(outcome)
+        if outcome.status == "error" and not continue_on_error:
+            break
+    return outcomes

hap_cli-0.7.2/hap_cli/core/editor/componentlower.py

@@ -0,0 +1,80 @@
+"""Lower a clean custom-page component definition into the wire shape.
+
+Covered well: value-based widgets — richText (2), embedUrl (3), image (8).
+For data-bound widgets (chart/view/filter/button) that need resolved ids
+or nested config, pass the wire object under ``raw`` (merged last, wins).
+
+Wire shape mirrors pd-openweb ``src/pages/customPage/util.js`` and the
+hap-cli-app-creator component builders: a widget carries ``type`` (int),
+``value``/config, ``name``, and per-platform ``web``/``mobile`` blocks
+holding the grid ``layout`` (48-col).
+"""
+from __future__ import annotations
+
+from typing import Any
+
+# clean type name -> numeric widget type.
+COMPONENT_TYPE = {
+    "chart": 1, "analysis": 1,
+    "richText": 2, "rich_text": 2,
+    "embedUrl": 3, "embed_url": 3,
+    "button": 4,
+    "view": 5,
+    "filter": 6,
+    "image": 8,
+    "carousel": 9,
+    "tabs": 10,
+    "card": 11,
+}
+
+# default 48-col grid size per type name.
+_DEFAULT_WH = {
+    "richText": (48, 5), "rich_text": (48, 5),
+    "embedUrl": (24, 12), "embed_url": (24, 12),
+    "image": (24, 12), "view": (48, 12), "chart": (24, 10),
+    "button": (24, 6), "filter": (24, 3),
+}
+
+
+def resolve_type(t) -> int:
+    if isinstance(t, int):
+        return t
+    if isinstance(t, str):
+        if t.isdigit():
+            return int(t)
+        if t in COMPONENT_TYPE:
+            return COMPONENT_TYPE[t]
+    raise ValueError(f"unknown component type: {t!r}")
+
+
+def lower_component(comp: dict[str, Any]) -> dict[str, Any]:
+    """Return the wire component dict for one clean component definition.
+
+    Clean form: ``{name, type, [value], [layout:{x,y,w,h}], [raw:{...}]}``.
+    """
+    type_name = comp["type"]
+    type_id = resolve_type(type_name)
+    w, h = _DEFAULT_WH.get(type_name, (24, 8))
+    layout = dict(comp.get("layout") or {})
+    layout.setdefault("x", 0)
+    layout.setdefault("y", 0)
+    layout.setdefault("w", w)
+    layout.setdefault("h", h)
+    layout.setdefault("minW", 2)
+    layout.setdefault("minH", 4)
+    # HAP does not round-trip a top-level ``name`` on a page component —
+    # the queryable/display name lives in ``web.title``. Set both so the
+    # editor can resolve the component by name on a later read.
+    wire: dict[str, Any] = {
+        "type": type_id,
+        "name": comp["name"],
+        "web": {"title": comp["name"], "titleVisible": True, "visible": True,
+                "layout": layout},
+        "mobile": {"title": comp["name"], "titleVisible": True,
+                   "visible": True, "layout": None},
+    }
+    if "value" in comp:
+        wire["value"] = comp["value"]
+    if isinstance(comp.get("raw"), dict):
+        wire.update(comp["raw"])
+    return wire

hap_cli-0.7.2/hap_cli/core/editor/editspec.py

@@ -0,0 +1,119 @@
+"""Load + validate an edit-spec against the per-module schemas.
+
+Validation is two-stage and module-local: the envelope schema checks the
+wrapper and each op's shared ``type``/``confirm`` fields; then, per op,
+only the one module schema named by the op.type prefix is loaded and used
+for deep validation (dispatched to the matching verb branch for precise
+errors).
+
+Schemas are canonical in the skill
+(``skills/hap-cli-app-editor/scripts/editspec/``). :func:`schema_dir`
+resolves them for both the editable/repo layout and a pip-installed wheel
+(where ``setup.py`` mirrors them into ``hap_cli/core/editor/editspec/``,
+the same trick used for the V3 schemas).
+"""
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+from hap_cli.core.editor import jsonschema_mini
+from hap_cli.core.editor.errors import EditSpecError
+
+# op.type prefix -> module schema filename.
+_MODULE_BY_PREFIX = {
+    "worksheet": "worksheet.schema.json",
+    "field": "field.schema.json",
+    "view": "view.schema.json",
+    "role": "role.schema.json",
+    "custom-action": "custom-action.schema.json",
+    "chatbot": "chatbot.schema.json",
+    "custom-page": "custom-page.schema.json",
+    "workflow": "workflow.schema.json",
+    "component": "component.schema.json",
+    "node": "node.schema.json",
+    "app": "application.schema.json",
+    "section": "application.schema.json",
+}
+
+DESTRUCTIVE_TYPES = {
+    "worksheet.delete", "field.delete", "view.delete", "role.delete",
+    "custom-action.delete", "chatbot.delete", "custom-page.delete",
+    "workflow.delete", "component.delete", "node.delete", "section.delete",
+}
+
+_SKILL_REL = ("skills", "hap-cli-app-editor", "scripts", "editspec")
+
+
+@lru_cache(maxsize=1)
+def schema_dir() -> Path:
+    """Locate the edit-spec schema directory.
+
+    Resolution order:
+      1. Wheel-bundled copy next to this module (``editspec/``), created
+         by setup.py's build step for installed packages.
+      2. Repo/editable layout: ``<repo>/skills/hap-cli-app-editor/
+         scripts/editspec`` found by walking up from this file.
+    """
+    bundled = Path(__file__).resolve().parent / "editspec"
+    if bundled.is_dir() and any(bundled.glob("*.schema.json")):
+        return bundled
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        cand = parent.joinpath(*_SKILL_REL)
+        if cand.is_dir():
+            return cand
+    raise EditSpecError([
+        "could not locate edit-spec schemas (neither the bundled copy nor "
+        "skills/hap-cli-app-editor/scripts/editspec)"])
+
+
+def _load_schema(filename: str) -> dict[str, Any]:
+    with (schema_dir() / filename).open(encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+def load_spec(path: Path) -> dict[str, Any]:
+    """Read an edit-spec JSON file and validate it. Returns the spec dict."""
+    try:
+        with Path(path).open(encoding="utf-8") as fh:
+            spec = json.load(fh)
+    except (OSError, json.JSONDecodeError) as exc:
+        raise EditSpecError([f"could not read edit-spec {path}: {exc}"]) from exc
+    validate_spec(spec)
+    return spec
+
+
+def validate_spec(spec: Any) -> None:
+    """Validate an already-parsed edit-spec; raise EditSpecError on problems."""
+    problems: list[str] = []
+    problems += jsonschema_mini.validate(spec, _load_schema("envelope.schema.json"))
+
+    if isinstance(spec, dict) and isinstance(spec.get("ops"), list):
+        for i, op in enumerate(spec["ops"]):
+            if not isinstance(op, dict):
+                continue
+            op_type = op.get("type")
+            if not isinstance(op_type, str) or "." not in op_type:
+                continue
+            prefix, verb = op_type.split(".", 1)
+            module = _MODULE_BY_PREFIX.get(prefix)
+            if module is None:
+                problems.append(f"ops[{i}].type: '{op_type}' has no module "
+                                f"schema (prefix '{prefix}' unsupported)")
+                continue
+            schema = _load_schema(module)
+            defs = schema.get("$defs") or {}
+            branch = defs.get(verb) or defs.get(
+                op_type.replace(".", "_").replace("-", "_"))
+            if branch is None:
+                problems.append(f"ops[{i}].type: '{op_type}' has no '{verb}' "
+                                f"branch in {module}")
+                continue
+            problems += jsonschema_mini.validate_against(
+                op, branch, schema, f"ops[{i}]")
+
+    if problems:
+        raise EditSpecError(problems)

hap_cli-0.7.2/hap_cli/core/editor/errors.py

@@ -0,0 +1,55 @@
+"""Exception types for the editor framework.
+
+Kept separate so handlers, the planner, and the CLI dispatch can all
+catch the same hierarchy without importing each other.
+"""
+from __future__ import annotations
+
+
+class EditorError(Exception):
+    """Base class for every error this framework raises."""
+
+
+class EditSpecError(EditorError):
+    """The edit-spec is structurally invalid (schema or shape).
+
+    Carries a list of human-readable problems, each prefixed with the
+    JSON path where it occurred, so the user can fix the spec before any
+    API call is made.
+    """
+
+    def __init__(self, problems: list[str]):
+        self.problems = problems
+        super().__init__("; ".join(problems) if problems else "invalid edit-spec")
+
+
+class ResolveError(EditorError):
+    """A logical name (worksheet/field/view/...) could not be resolved to
+    an id against the live app structure."""
+
+
+class ConfirmRequiredError(EditorError):
+    """A destructive op was requested without ``confirm: true``.
+
+    Destructive operations (delete / overwrite) refuse to run unless the
+    op object explicitly opts in — a guard against accidental data loss.
+    """
+
+
+class HapCommandError(EditorError):
+    """The ``hap`` binary exited non-zero or returned an API error."""
+
+    def __init__(self, message: str, *, argv=None, returncode=None,
+                 stderr: str = ""):
+        self.argv = argv
+        self.returncode = returncode
+        self.stderr = stderr
+        super().__init__(message)
+
+
+class NotLoggedInError(HapCommandError):
+    """The ``hap`` session is not authenticated.
+
+    The user must run ``hap auth login`` (and select an org) before any
+    live read or write can happen.
+    """

hap_cli-0.7.2/hap_cli/core/editor/fieldlower.py

@@ -0,0 +1,66 @@
+"""Lower a clean field definition into a raw HAP control dict.
+
+The clean form is what an edit-spec carries:
+``{"name": "金额", "type": "Number", "required": true, ...}``. HAP's
+``AddWorksheetControls`` / ``SaveWorksheetControls`` accept partial
+control objects and fill per-type defaults server-side, so the lowering
+only needs to set the discriminating keys.
+
+Covered well: scalar types (Text/Number/Date/Email/...) and select types
+(SingleSelect/MultipleSelect/Dropdown, with options). For advanced types
+(Relation/Lookup/Rollup/Formula/SubTable) pass a raw override under the
+field's ``control`` key — it is merged last and wins.
+"""
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from hap_cli.core.editor._hapmeta import control_type_codes as codes
+
+_OPTION_COLORS = [
+    "#C9E6FC", "#C3F2F2", "#C2F1D2", "#FFE7B1", "#FBD2BF",
+    "#FDD2DC", "#E6CFF1", "#D2D2D2",
+]
+
+
+def _normalize_options(opts: list) -> list[dict[str, Any]]:
+    """Mirror the CLI's option shape (key/value/index/checked/color)."""
+    out: list[dict[str, Any]] = []
+    any_default = any(isinstance(o, dict) and o.get("checked") for o in opts)
+    for i, o in enumerate(opts):
+        if isinstance(o, dict):
+            out.append({
+                "key": o.get("key") or str(uuid.uuid4()),
+                "value": o["value"],
+                "isDeleted": o.get("isDeleted", False),
+                "index": o.get("index", i + 1),
+                "checked": o.get("checked", False),
+                "color": o.get("color", _OPTION_COLORS[i % len(_OPTION_COLORS)]),
+            })
+        else:
+            out.append({
+                "key": str(uuid.uuid4()),
+                "value": str(o),
+                "isDeleted": False,
+                "index": i + 1,
+                "checked": (not any_default and i == 0),
+                "color": _OPTION_COLORS[i % len(_OPTION_COLORS)],
+            })
+    return out
+
+
+def lower_field(field: dict[str, Any]) -> dict[str, Any]:
+    """Return the raw control dict for one clean field definition."""
+    type_id = codes.resolve(field["type"])
+    ctrl: dict[str, Any] = {"type": type_id, "controlName": field["name"]}
+    if field.get("required"):
+        ctrl["required"] = True
+    if field.get("unique"):
+        ctrl["unique"] = True
+    if type_id in codes.SELECT_TYPE_IDS and field.get("options") is not None:
+        ctrl["options"] = _normalize_options(field["options"])
+    # Raw escape hatch for advanced types — merged last, wins.
+    if isinstance(field.get("control"), dict):
+        ctrl.update(field["control"])
+    return ctrl