xmemcli 0.0.1__py3-none-any.whl

xmemcli/_instance_schema.py

@@ -0,0 +1,769 @@
+"""Instance lifecycle and XMD/schema workflow commands for ``xmemcli``.
+
+Imported lazily from ``xmem._build_parser`` so ``xmem`` finishes loading before we bind helpers.
+"""
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any, Protocol
+from urllib.parse import urlencode
+
+from ._output import CliOutput, OutputKind, make_error
+from ._xmem_bridge import curate_instance, http_to_exit, xmem_module
+
+try:
+    import yaml as _yaml
+except ImportError:
+    _yaml = None
+
+
+def _yaml_dump_or_json(value: Any) -> str:
+    if _yaml is not None:
+        return _yaml.safe_dump(value, sort_keys=False, default_flow_style=False)
+    return json.dumps(value, indent=2) + "\n"
+
+
+def _infer_schema_type(path: str | None, explicit: str | None) -> str:
+    if explicit:
+        return explicit
+    if path and Path(path).suffix.lower() == ".json":
+        return "json"
+    return "yaml"
+
+
+def _build_instance_schema_payload(schema_text: str, schema_type: str) -> dict[str, Any]:
+    if schema_type == "json":
+        return {"json_schema": {"value": schema_text}}
+    return {"yml": {"value": schema_text}}
+
+
+def _extract_limit_message(body: str) -> tuple[str, str] | None:
+    try:
+        data = json.loads(body)
+        err = (data.get("errors") or [{}])[0]
+        if err.get("console_url"):
+            return (err.get("message") or "instance limit reached"), err["console_url"]
+    except (json.JSONDecodeError, KeyError, IndexError, TypeError):
+        # Envelope shape varies across API versions; ignore malformed bodies.
+        pass
+    return None
+
+
+def _resolve_instance_id(args: argparse.Namespace) -> str | None:
+    m = xmem_module()
+    explicit = getattr(args, "instance_id_arg", None)
+    if explicit:
+        return explicit
+    if args.instance_id:
+        return args.instance_id
+    return os.environ.get(m.ENV_INSTANCE_ID)
+
+
+def _require_instance_id(args: argparse.Namespace) -> tuple[str | None, tuple[CliOutput, int] | None]:
+    m = xmem_module()
+    instance_id = _resolve_instance_id(args)
+    if not instance_id:
+        return (
+            None,
+            (
+                make_error(
+                    f"instance id required (positional arg or ${m.ENV_INSTANCE_ID})",
+                    stage="usage",
+                ),
+                m.EXIT_USAGE,
+            ),
+        )
+    return instance_id, None
+
+
+def _read_schema_mutation_payload(
+    args: argparse.Namespace,
+) -> tuple[dict[str, Any] | None, tuple[CliOutput, int] | None]:
+    if not args.schema_file:
+        return None, (make_error("--schema-file is required", stage="usage"), xmem_module().EXIT_USAGE)
+    try:
+        schema_text = Path(args.schema_file).read_text(encoding="utf-8")
+    except OSError as exc:
+        return None, (make_error(f"cannot read {args.schema_file}: {exc}", stage="usage"), xmem_module().EXIT_USAGE)
+    schema_type = _infer_schema_type(args.schema_file, getattr(args, "schema_type", None))
+    payload: dict[str, Any] = {
+        "instance_schema": _build_instance_schema_payload(schema_text, schema_type),
+        "confirm_destructive": bool(getattr(args, "confirm_destructive", False)),
+    }
+    migration_plan = getattr(args, "migration_plan", None)
+    if migration_plan:
+        try:
+            payload["migration_plan"] = json.loads(Path(migration_plan).read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            return None, (make_error(f"cannot read migration_plan: {exc}", stage="usage"), xmem_module().EXIT_USAGE)
+    return payload, None
+
+
+def _parse_schema_mutation_error_body(body: str) -> tuple[str, str, dict[str, Any]]:
+    """Return (error_type, message, details) from a schema apply/dry-run 422 body."""
+    try:
+        data = json.loads(body)
+    except json.JSONDecodeError:
+        return "", body, {}
+
+    if isinstance(data, dict) and data.get("error_type"):
+        raw_details = data.get("details")
+        details: dict[str, Any] = raw_details if isinstance(raw_details, dict) else {}
+        return (
+            str(data.get("error_type") or ""),
+            str(data.get("error_message") or data.get("message") or body),
+            details,
+        )
+
+    err = (data.get("errors") or [{}])[0] if isinstance(data, dict) else {}
+    if isinstance(err, dict):
+        raw_details = err.get("details")
+        details = raw_details if isinstance(raw_details, dict) else {}
+        return (
+            str(err.get("code") or err.get("error_type") or ""),
+            str(err.get("message") or err.get("error_message") or body),
+            details,
+        )
+    return "", body, {}
+
+
+class _SchemaApiError(Protocol):
+    status: int
+    body: str
+
+
+def _handle_schema_mutation_error(e: _SchemaApiError, *, instance_id: str) -> tuple[CliOutput, int]:
+    m = xmem_module()
+    if e.status == 422:
+        error_type, msg, details = _parse_schema_mutation_error_body(e.body)
+        code = error_type.lower()
+
+        if code == "non_additive_change_requires_plan":
+            return (
+                make_error(
+                    f"non-additive change requires --migration-plan "
+                    f"(produce one with `{m.CLI_NAME} xmd enhance --plan-output`)",
+                    status=e.status,
+                    stage="plan_required",
+                ),
+                m.EXIT_HTTP_ERROR,
+            )
+        if code == "plan_validation_failed":
+            detail_bits: list[str] = []
+            for key in ("uncovered_non_additive", "uncovered_additive_ops", "missing_additive_ops"):
+                items = details.get(key)
+                if isinstance(items, list) and items:
+                    detail_bits.append(f"{key}={len(items)}")
+            suffix = f" ({', '.join(detail_bits)})" if detail_bits else ""
+            return (
+                make_error(f"{msg}{suffix}", status=e.status, stage="validate"),
+                m.EXIT_HTTP_ERROR,
+            )
+        if code == "destructive_confirmation_required" or (
+            "destructive" in code and "confirmation" in code
+        ):
+            return (
+                make_error(
+                    "destructive change requires --confirm-destructive",
+                    status=e.status,
+                    stage="destructive",
+                ),
+                m.EXIT_HTTP_ERROR,
+            )
+        # Legacy envelopes: only map explicit plan-required codes, not substrings in details.
+        if code in ("non_additive", "non_additive_change") or (
+            not error_type and "non_additive_change_requires" in msg.lower()
+        ):
+            return (
+                make_error(
+                    f"non-additive change requires --migration-plan "
+                    f"(produce one with `{m.CLI_NAME} xmd enhance --plan-output`)",
+                    status=e.status,
+                    stage="plan_required",
+                ),
+                m.EXIT_HTTP_ERROR,
+            )
+        if "destructive" in code or (not error_type and "destructive" in msg.lower()):
+            return (
+                make_error(
+                    "destructive change requires --confirm-destructive",
+                    status=e.status,
+                    stage="destructive",
+                ),
+                m.EXIT_HTTP_ERROR,
+            )
+        return (make_error(msg, status=e.status, stage="validate"), m.EXIT_HTTP_ERROR)
+    if e.status == 404:
+        return (
+            make_error(f"instance {instance_id} not found", status=e.status, stage="request"),
+            m.EXIT_HTTP_ERROR,
+        )
+    if e.status in (401, 403):
+        return (make_error(str(e), status=e.status, stage="auth"), m.EXIT_AUTH_ERROR)
+    return (make_error(str(e), status=e.status, stage="request"), m.EXIT_HTTP_ERROR)
+
+
+def _get_with_query(url: str, api_key: str, params: dict[str, Any], *, timeout_s: float = 30.0) -> dict[str, Any]:
+    m = xmem_module()
+    query = urlencode({k: v for k, v in params.items() if v is not None})
+    full_url = f"{url}?{query}" if query else url
+    return m._get(full_url, api_key, timeout_s=timeout_s)
+
+
+def cmd_instance_get(args: argparse.Namespace) -> tuple[CliOutput, int]:
+    m = xmem_module()
+    api_key, _ = m._require(args, need_instance=False)
+    base = m._api_url(args)
+    instance_id = args.instance_id_arg
+
+    explicit_cluster = getattr(args, "cluster", None)
+    if explicit_cluster:
+        cluster_ids = [explicit_cluster]
+    else:
+        try:
+            clusters_env = m._get(f"{base}/clusters?verbose=true", api_key)
+        except m.ApiError as e:
+            return (make_error(f"/clusters failed: {e}", status=e.status), http_to_exit(e.status))
+        cluster_ids = [c["id"] for c in (clusters_env.get("items") or []) if isinstance(c, dict) and c.get("id")]
+
+    last_auth_error: m.ApiError | None = None
+    for cid in cluster_ids:
+        try:
+            envelope = m._get(f"{base}/clusters/{cid}/instances/{instance_id}", api_key)
+        except m.ApiError as e:
+            if e.status == 404:
+                continue
+            if e.status in (401, 403):
+                last_auth_error = e
+                continue
+            return (make_error(str(e), status=e.status, stage="request"), m.EXIT_HTTP_ERROR)
+        item = m._unwrap_items(envelope)
+        return (CliOutput(OutputKind.INSTANCE_GET, curate_instance(item, args.verbose)), m.EXIT_OK)
+
+    if last_auth_error is not None:
+        return (
+            make_error(
+                f"instance {instance_id} exists in a cluster this key cannot access",
+                status=last_auth_error.status,
+                stage="auth",
+            ),
+            m.EXIT_AUTH_ERROR,
+        )
+    return (
+        make_error(
+            f"instance {instance_id} not found in any cluster visible to this key",
+            status=404,
+            stage="request",
+        ),
+        m.EXIT_HTTP_ERROR,
+    )
+
+
+def _require_interactive_yes(prompt: str) -> tuple[bool, str | None]:
+    """Return (True, None) when the user typed ``yes`` on a real TTY."""
+    if not sys.stdin.isatty():
+        return False, "instance delete requires an interactive terminal; type yes when prompted (do not pipe yes)"
+    try:
+        # DELIBERATELY print: confirmation prompt must not pollute stdout in machine mode.
+        print(prompt, end="", file=sys.stderr, flush=True)
+        answer = input().strip().lower()
+    except EOFError:
+        return False, "instance delete aborted (confirmation required; type yes)"
+    if answer != "yes":
+        return False, "instance delete aborted (confirmation required; type yes)"
+    return True, None
+
+
+def cmd_instance_delete(args: argparse.Namespace) -> tuple[CliOutput, int]:
+    """Delete an instance after interactive confirmation.
+
+    Partial by design: human operators at a real TTY must type ``yes``; piped or
+    non-interactive stdin is refused. Agents, harnesses, and automation must use
+    ``DELETE /instances/{id}`` over HTTP instead — see ``cli/HARNESS-FIRST-TEST.md``
+    step 41.
+    """
+    m = xmem_module()
+    api_key, _ = m._require(args, need_instance=False)
+    base = m._api_url(args)
+
+    explicit_id = getattr(args, "instance_id_arg", None)
+    if explicit_id:
+        instance_id = str(explicit_id)
+    else:
+        _, resolved = m._require(args, need_instance=True)
+        instance_id = str(resolved)
+
+    name = instance_id
+    try:
+        lookup = m._get(f"{base.rstrip('/')}/instances/{instance_id}", api_key)
+        item = m._unwrap_items(lookup)
+        if isinstance(item, dict) and item.get("name"):
+            name = str(item["name"])
+    except m.ApiError:
+        pass
+
+    ok, err = _require_interactive_yes(
+        f"Delete instance {instance_id} ({name})? Type yes to confirm: "
+    )
+    if not ok:
+        return (make_error(err or "instance delete aborted", stage="usage"), m.EXIT_USAGE)
+
+    try:
+        envelope = m._delete(f"{base.rstrip('/')}/instances/{instance_id}", api_key)
+    except m.ApiError as e:
+        if e.status in (401, 403):
+            return (make_error(str(e), status=e.status, stage="auth"), m.EXIT_AUTH_ERROR)
+        if e.status == 404:
+            return (
+                make_error(f"instance {instance_id} not found", status=e.status, stage="request"),
+                m.EXIT_HTTP_ERROR,
+            )
+        return (make_error(str(e), status=e.status, stage="request"), m.EXIT_HTTP_ERROR)
+
+    deleted_id = instance_id
+    if isinstance(envelope, dict):
+        items = envelope.get("items")
+        if isinstance(items, list) and items and isinstance(items[0], dict) and items[0].get("id"):
+            deleted_id = str(items[0]["id"])
+        elif envelope.get("id"):
+            deleted_id = str(envelope["id"])
+
+    return (
+        CliOutput(
+            OutputKind.INSTANCE_DELETE,
+            {"instance_id": deleted_id, "name": name, "status": "deleted"},
+        ),
+        m.EXIT_OK,
+    )
+
+
+def cmd_instance_create(args: argparse.Namespace) -> tuple[CliOutput, int]:
+    m = xmem_module()
+    api_key, _ = m._require(args, need_instance=False)
+    base = m._api_url(args)
+    cluster_id, cluster_err = m._resolve_cluster_id(args, base, api_key)
+    if cluster_err is not None:
+        return cluster_err
+    if not cluster_id:
+        return (make_error("could not resolve cluster_id", stage="usage"), m.EXIT_USAGE)
+
+    if args.schema_stdin and args.schema_file:
+        return (
+            make_error("pass either --schema-file or --schema-stdin, not both", stage="usage"),
+            m.EXIT_USAGE,
+        )
+    if args.schema_stdin:
+        schema_text = sys.stdin.read()
+        schema_type = _infer_schema_type(None, args.schema_type)
+    elif args.schema_file:
+        try:
+            schema_text = Path(args.schema_file).read_text(encoding="utf-8")
+        except OSError as exc:
+            return (make_error(f"cannot read {args.schema_file}: {exc}", stage="usage"), m.EXIT_USAGE)
+        schema_type = _infer_schema_type(args.schema_file, args.schema_type)
+    else:
+        return (make_error("--schema-file or --schema-stdin is required", stage="usage"), m.EXIT_USAGE)
+
+    payload: dict[str, Any] = {
+        "name": args.name,
+        "instance_schema": _build_instance_schema_payload(schema_text, schema_type),
+    }
+    if args.description:
+        payload["description"] = args.description
+
+    try:
+        envelope = m._post(
+            f"{base}/clusters/{cluster_id}/instances",
+            payload,
+            api_key,
+            timeout_s=180.0,
+        )
+    except m.ApiError as e:
+        if e.status == 403:
+            limit = _extract_limit_message(e.body)
+            if limit is not None:
+                msg, console_url = limit
+                return (
+                    make_error(f"{msg} (see {console_url})", status=e.status, stage="limit"),
+                    m.EXIT_HTTP_ERROR,
+                )
+            return (make_error(str(e), status=e.status, stage="auth"), m.EXIT_AUTH_ERROR)
+        if e.status == 401:
+            return (make_error(str(e), status=e.status, stage="auth"), m.EXIT_AUTH_ERROR)
+        return (make_error(str(e), status=e.status, stage="request"), m.EXIT_HTTP_ERROR)
+
+    item = m._unwrap_items(envelope)
+    curated: dict[str, Any] = {
+        "instance_id": item.get("id"),
+        "name": item.get("name"),
+        "console_url": item.get("console_url"),
+    }
+    if args.verbose:
+        for key in ("trace_id", "data_schema", "cluster_id"):
+            if key in item and item[key] is not None:
+                curated[key] = item[key]
+    return (CliOutput(OutputKind.INSTANCE_CREATE, curated), m.EXIT_OK)
+
+
+def cmd_xmd_generate(args: argparse.Namespace) -> tuple[CliOutput, int]:
+    m = xmem_module()
+    api_key, _ = m._require(args, need_instance=False)
+    base = m._api_url(args)
+    cluster_id, cluster_err = m._resolve_cluster_id(args, base, api_key)
+    if cluster_err is not None:
+        return cluster_err
+    if not cluster_id:
+        return (make_error("could not resolve cluster_id", stage="usage"), m.EXIT_USAGE)
+    payload = {"schema_description": args.description}
+    try:
+        envelope = m._post(
+            f"{base}/clusters/{cluster_id}/instances/generate_schema",
+            payload,
+            api_key,
+            timeout_s=120.0,
+        )
+    except m.ApiError as e:
+        if e.status in (401, 403):
+            return (make_error(str(e), status=e.status, stage="auth"), m.EXIT_AUTH_ERROR)
+        return (make_error(str(e), status=e.status, stage="request"), m.EXIT_HTTP_ERROR)
+    item = m._unwrap_items(envelope)
+    schema = item.get("data_schema") if isinstance(item, dict) else None
+    if args.output and schema is not None:
+        Path(args.output).write_text(_yaml_dump_or_json(schema), encoding="utf-8")
+    return (CliOutput(OutputKind.XMD_SCHEMA, item), m.EXIT_OK)
+
+
+def cmd_xmd_enhance(args: argparse.Namespace) -> tuple[CliOutput, int]:
+    m = xmem_module()
+    api_key, _ = m._require(args, need_instance=False)
+    base = m._api_url(args)
+    cluster_id, cluster_err = m._resolve_cluster_id(args, base, api_key)
+    if cluster_err is not None:
+        return cluster_err
+    if not cluster_id:
+        return (make_error("could not resolve cluster_id", stage="usage"), m.EXIT_USAGE)
+
+    from_instance = bool(getattr(args, "from_instance", False))
+    schema_file = getattr(args, "schema_file", None)
+    if from_instance and schema_file:
+        return (
+            make_error("pass either --from-instance or a schema_file, not both", stage="usage"),
+            m.EXIT_USAGE,
+        )
+    if from_instance:
+        instance_id, id_err = _require_instance_id(args)
+        if id_err is not None:
+            return id_err
+        if instance_id is None:
+            return (make_error("instance id required", stage="usage"), m.EXIT_USAGE)
+        try:
+            envelope = m._get(f"{base}/instances/{instance_id}/schema", api_key)
+        except m.ApiError as e:
+            if e.status == 404:
+                return (
+                    make_error(f"instance {instance_id} not found", status=e.status, stage="request"),
+                    m.EXIT_HTTP_ERROR,
+                )
+            if e.status in (401, 403):
+                return (make_error(str(e), status=e.status, stage="auth"), m.EXIT_AUTH_ERROR)
+            return (make_error(str(e), status=e.status, stage="request"), m.EXIT_HTTP_ERROR)
+        item = m._unwrap_items(envelope)
+        schema = item.get("data_schema") if isinstance(item, dict) else None
+        if schema is None:
+            return (make_error("instance has no live schema to enhance", stage="usage"), m.EXIT_USAGE)
+        current_yaml = _yaml_dump_or_json(schema)
+    elif schema_file:
+        try:
+            current_yaml = Path(schema_file).read_text(encoding="utf-8")
+        except OSError as exc:
+            return (make_error(f"cannot read {schema_file}: {exc}", stage="usage"), m.EXIT_USAGE)
+    else:
+        return (
+            make_error(
+                "schema_file or --from-instance is required "
+                "(MCP enhance_schema uses the bound instance; pass --from-instance with an instance id)",
+                stage="usage",
+            ),
+            m.EXIT_USAGE,
+        )
+
+    payload = {"schema_description": args.description, "current_yml_schema": current_yaml}
+    try:
+        envelope = m._post(
+            f"{base}/clusters/{cluster_id}/instances/generate_schema",
+            payload,
+            api_key,
+            timeout_s=120.0,
+        )
+    except m.ApiError as e:
+        if e.status in (401, 403):
+            return (make_error(str(e), status=e.status, stage="auth"), m.EXIT_AUTH_ERROR)
+        return (make_error(str(e), status=e.status, stage="request"), m.EXIT_HTTP_ERROR)
+    item = m._unwrap_items(envelope)
+    migration_plan = item.get("migration_plan") if isinstance(item, dict) else None
+    if args.output and isinstance(item, dict) and item.get("data_schema") is not None:
+        Path(args.output).write_text(_yaml_dump_or_json(item["data_schema"]), encoding="utf-8")
+    if args.plan_output and isinstance(item, dict):
+        Path(args.plan_output).write_text(json.dumps(item.get("migration_plan") or {}, indent=2), encoding="utf-8")
+    return (CliOutput(OutputKind.XMD_ENHANCE, item), m.EXIT_OK)
+
+
+def _xmd_validate_impl(
+    args: argparse.Namespace,
+    *,
+    format_hint: str | None,
+) -> tuple[CliOutput, int]:
+    m = xmem_module()
+    api_key, _ = m._require(args, need_instance=False)
+    base = m._api_url(args)
+    cluster_id, cluster_err = m._resolve_cluster_id(args, base, api_key)
+    if cluster_err is not None:
+        return cluster_err
+    if not cluster_id:
+        return (make_error("could not resolve cluster_id", stage="usage"), m.EXIT_USAGE)
+    try:
+        text = Path(args.schema_file).read_text(encoding="utf-8")
+    except OSError as exc:
+        return (make_error(f"cannot read {args.schema_file}: {exc}", stage="usage"), m.EXIT_USAGE)
+
+    use_json = format_hint == "json" or (
+        format_hint is None and Path(args.schema_file).suffix.lower() == ".json"
+    )
+    if use_json:
+        try:
+            js = json.loads(text)
+        except json.JSONDecodeError as exc:
+            return (make_error(f"invalid JSON in {args.schema_file}: {exc}", stage="usage"), m.EXIT_USAGE)
+        url_path = f"/clusters/{cluster_id}/instances/validate_json_schema"
+        body: dict[str, Any] = {"json_schema": js}
+    else:
+        url_path = f"/clusters/{cluster_id}/instances/validate_yaml_schema"
+        body = {"yml_schema": text}
+    try:
+        envelope = m._post(f"{base}{url_path}", body, api_key, timeout_s=30.0)
+    except m.ApiError as e:
+        if e.status in (401, 403):
+            return (make_error(str(e), status=e.status, stage="auth"), m.EXIT_AUTH_ERROR)
+        return (make_error(str(e), status=e.status, stage="validate"), m.EXIT_HTTP_ERROR)
+    item = m._unwrap_items(envelope)
+    return (CliOutput(OutputKind.XMD_SCHEMA, item), m.EXIT_OK)
+
+
+def cmd_xmd_validate(args: argparse.Namespace) -> tuple[CliOutput, int]:
+    return _xmd_validate_impl(args, format_hint=None)
+
+
+def cmd_xmd_validate_yaml(args: argparse.Namespace) -> tuple[CliOutput, int]:
+    return _xmd_validate_impl(args, format_hint="yaml")
+
+
+def cmd_xmd_validate_json(args: argparse.Namespace) -> tuple[CliOutput, int]:
+    return _xmd_validate_impl(args, format_hint="json")
+
+
+def cmd_xmd_convert(args: argparse.Namespace) -> tuple[CliOutput, int]:
+    """Convert JSON Schema to XMD YAML via ``POST …/validate_json_schema``."""
+    m = xmem_module()
+    api_key, _ = m._require(args, need_instance=False)
+    base = m._api_url(args)
+    cluster_id, cluster_err = m._resolve_cluster_id(args, base, api_key)
+    if cluster_err is not None:
+        return cluster_err
+    if not cluster_id:
+        return (make_error("could not resolve cluster_id", stage="usage"), m.EXIT_USAGE)
+
+    input_file = Path(args.schema_file)
+    if not input_file.is_file():
+        return (make_error(f"cannot read {args.schema_file}: file not found", stage="usage"), m.EXIT_USAGE)
+    try:
+        json_schema = json.loads(input_file.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        return (make_error(f"invalid JSON in {args.schema_file}: {exc}", stage="usage"), m.EXIT_USAGE)
+    except OSError as exc:
+        return (make_error(f"cannot read {args.schema_file}: {exc}", stage="usage"), m.EXIT_USAGE)
+
+    root_object = getattr(args, "root_object", None) or "MainObject"
+    body: dict[str, Any] = {"json_schema": json_schema, "root_object_name": root_object}
+    try:
+        envelope = m._post(
+            f"{base}/clusters/{cluster_id}/instances/validate_json_schema",
+            body,
+            api_key,
+            timeout_s=30.0,
+        )
+    except m.ApiError as e:
+        if e.status in (401, 403):
+            return (make_error(str(e), status=e.status, stage="auth"), m.EXIT_AUTH_ERROR)
+        return (make_error(str(e), status=e.status, stage="convert"), m.EXIT_HTTP_ERROR)
+
+    item = m._unwrap_items(envelope)
+    data_schema = item.get("data_schema") if isinstance(item, dict) else None
+    if not isinstance(data_schema, dict):
+        return (make_error("conversion returned no data_schema", stage="convert"), m.EXIT_HTTP_ERROR)
+
+    output_file = Path(args.output) if args.output else input_file.with_suffix(".yml")
+    try:
+        output_file.parent.mkdir(parents=True, exist_ok=True)
+        output_file.write_text(_yaml_dump_or_json(data_schema), encoding="utf-8")
+    except OSError as exc:
+        return (make_error(f"cannot write {output_file}: {exc}", stage="convert"), m.EXIT_HTTP_ERROR)
+
+    message = f"Successfully converted '{args.schema_file}' to '{output_file}'\n"
+    return (CliOutput(OutputKind.XMD_CONVERT, {"message": message}), m.EXIT_OK)
+
+
+def cmd_schema_get(args: argparse.Namespace) -> tuple[CliOutput, int]:
+    m = xmem_module()
+    api_key, _ = m._require(args, need_instance=False)
+    instance_id, id_err = _require_instance_id(args)
+    if id_err is not None:
+        return id_err
+    if instance_id is None:
+        return (make_error("instance id required", stage="usage"), m.EXIT_USAGE)
+    base = m._api_url(args)
+    try:
+        envelope = m._get(f"{base}/instances/{instance_id}/schema", api_key)
+    except m.ApiError as e:
+        if e.status == 404:
+            return (
+                make_error(f"instance {instance_id} not found", status=e.status, stage="request"),
+                m.EXIT_HTTP_ERROR,
+            )
+        if e.status in (401, 403):
+            return (make_error(str(e), status=e.status, stage="auth"), m.EXIT_AUTH_ERROR)
+        return (make_error(str(e), status=e.status, stage="request"), m.EXIT_HTTP_ERROR)
+    item = m._unwrap_items(envelope)
+    schema = item.get("data_schema") if isinstance(item, dict) else None
+    if args.output and schema is not None:
+        Path(args.output).write_text(_yaml_dump_or_json(schema), encoding="utf-8")
+    return (CliOutput(OutputKind.XMD_SCHEMA, item), m.EXIT_OK)
+
+
+def cmd_schema_update(args: argparse.Namespace) -> tuple[CliOutput, int]:
+    m = xmem_module()
+    api_key, _ = m._require(args, need_instance=False)
+    instance_id, id_err = _require_instance_id(args)
+    if id_err is not None:
+        return id_err
+    if instance_id is None:
+        return (make_error("instance id required", stage="usage"), m.EXIT_USAGE)
+    payload, payload_err = _read_schema_mutation_payload(args)
+    if payload_err is not None:
+        return payload_err
+    if payload is None:
+        return (make_error("--schema-file is required", stage="usage"), m.EXIT_USAGE)
+    base = m._api_url(args)
+    try:
+        envelope = m._put(
+            f"{base}/instances/{instance_id}/schema",
+            payload,
+            api_key,
+            timeout_s=300.0,
+        )
+    except m.ApiError as e:
+        return _handle_schema_mutation_error(e, instance_id=instance_id)
+    item = m._unwrap_items(envelope)
+    return (CliOutput(OutputKind.SCHEMA_UPDATE, item), m.EXIT_OK)
+
+
+def cmd_schema_dry_run(args: argparse.Namespace) -> tuple[CliOutput, int]:
+    m = xmem_module()
+    api_key, _ = m._require(args, need_instance=False)
+    instance_id, id_err = _require_instance_id(args)
+    if id_err is not None:
+        return id_err
+    if instance_id is None:
+        return (make_error("instance id required", stage="usage"), m.EXIT_USAGE)
+    payload, payload_err = _read_schema_mutation_payload(args)
+    if payload_err is not None:
+        return payload_err
+    if payload is None:
+        return (make_error("--schema-file is required", stage="usage"), m.EXIT_USAGE)
+    base = m._api_url(args)
+    try:
+        envelope = m._post(
+            f"{base}/instances/{instance_id}/migrations/dry_run",
+            payload,
+            api_key,
+            timeout_s=120.0,
+        )
+    except m.ApiError as e:
+        return _handle_schema_mutation_error(e, instance_id=instance_id)
+    item = m._unwrap_items(envelope)
+    return (CliOutput(OutputKind.SCHEMA_DRY_RUN, item), m.EXIT_OK)
+
+
+def cmd_schema_migrations_list(args: argparse.Namespace) -> tuple[CliOutput, int]:
+    m = xmem_module()
+    api_key, _ = m._require(args, need_instance=False)
+    instance_id, id_err = _require_instance_id(args)
+    if id_err is not None:
+        return id_err
+    if instance_id is None:
+        return (make_error("instance id required", stage="usage"), m.EXIT_USAGE)
+    base = m._api_url(args)
+    params: dict[str, Any] = {
+        "limit": getattr(args, "limit", 50),
+        "include_yaml": str(bool(getattr(args, "include_yaml", False))).lower(),
+    }
+    before_id = getattr(args, "before_id", None)
+    if before_id:
+        params["before_id"] = before_id
+    try:
+        envelope = _get_with_query(
+            f"{base}/instances/{instance_id}/migrations",
+            api_key,
+            params,
+        )
+    except m.ApiError as e:
+        if e.status == 404:
+            return (
+                make_error(f"instance {instance_id} not found", status=e.status, stage="request"),
+                m.EXIT_HTTP_ERROR,
+            )
+        if e.status in (401, 403):
+            return (make_error(str(e), status=e.status, stage="auth"), m.EXIT_AUTH_ERROR)
+        return (make_error(str(e), status=e.status, stage="request"), m.EXIT_HTTP_ERROR)
+    item = m._unwrap_items(envelope)
+    return (CliOutput(OutputKind.SCHEMA_MIGRATIONS, item), m.EXIT_OK)
+
+
+def cmd_schema_migrations_get(args: argparse.Namespace) -> tuple[CliOutput, int]:
+    m = xmem_module()
+    api_key, _ = m._require(args, need_instance=False)
+    instance_id, id_err = _require_instance_id(args)
+    if id_err is not None:
+        return id_err
+    if instance_id is None:
+        return (make_error("instance id required", stage="usage"), m.EXIT_USAGE)
+    migration_id = getattr(args, "migration_id_arg", None)
+    if not migration_id:
+        return (make_error("migration_id is required", stage="usage"), m.EXIT_USAGE)
+    base = m._api_url(args)
+    params: dict[str, Any] = {
+        "include_yaml": str(bool(getattr(args, "include_yaml", False))).lower(),
+    }
+    try:
+        envelope = _get_with_query(
+            f"{base}/instances/{instance_id}/migrations/{migration_id}",
+            api_key,
+            params,
+        )
+    except m.ApiError as e:
+        if e.status == 404:
+            return (
+                make_error(
+                    f"migration {migration_id} not found for instance {instance_id}",
+                    status=e.status,
+                    stage="request",
+                ),
+                m.EXIT_HTTP_ERROR,
+            )
+        if e.status in (401, 403):
+            return (make_error(str(e), status=e.status, stage="auth"), m.EXIT_AUTH_ERROR)
+        return (make_error(str(e), status=e.status, stage="request"), m.EXIT_HTTP_ERROR)
+    item = m._unwrap_items(envelope)
+    return (CliOutput(OutputKind.SCHEMA_MIGRATIONS, item), m.EXIT_OK)