@josephyan/qingflow-app-builder-mcp 1.0.9 → 1.1.2

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

@@ -10,7 +10,11 @@ from .common import load_list_arg, load_object_arg, raise_config_error, require_
 
 def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
     parser = subparsers.add_parser("record", help="记录与表结构")
-    record_subparsers = parser.add_subparsers(dest="record_command", required=True)
+    record_subparsers = parser.add_subparsers(
+        dest="record_command",
+        required=True,
+        metavar="{schema,list,access,get,logs,insert,update,delete,member-candidates,department-candidates,code-block-run}",
+    )
 
     schema = record_subparsers.add_parser("schema", help="读取记录相关表结构")
     schema.add_argument("--mode", dest="legacy_mode", help=argparse.SUPPRESS)
@@ -43,13 +47,37 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     schema_code_block.add_argument("--app-key", required=True)
     schema_code_block.set_defaults(handler=_handle_schema_code_block, format_hint="")
 
+    member_candidates = record_subparsers.add_parser("member-candidates", help="读取成员字段候选项")
+    member_candidates.add_argument("--app-key", required=True)
+    member_candidates.add_argument("--field-id", type=int, required=True)
+    member_candidates.add_argument("--keyword", default="")
+    member_candidates.add_argument("--page-num", type=int, default=1)
+    member_candidates.add_argument("--page-size", type=int, default=20)
+    member_candidates.add_argument("--record-id")
+    member_candidates.add_argument("--workflow-node-id", type=int)
+    member_candidates.add_argument("--fields-file")
+    member_candidates.set_defaults(handler=_handle_member_candidates, format_hint="")
+
+    department_candidates = record_subparsers.add_parser("department-candidates", help="读取部门字段候选项")
+    department_candidates.add_argument("--app-key", required=True)
+    department_candidates.add_argument("--field-id", type=int, required=True)
+    department_candidates.add_argument("--keyword", default="")
+    department_candidates.add_argument("--page-num", type=int, default=1)
+    department_candidates.add_argument("--page-size", type=int, default=20)
+    department_candidates.add_argument("--record-id")
+    department_candidates.add_argument("--workflow-node-id", type=int)
+    department_candidates.add_argument("--fields-file")
+    department_candidates.set_defaults(handler=_handle_department_candidates, format_hint="")
+
     list_parser = record_subparsers.add_parser("list", help="列出记录")
     list_parser.add_argument("--app-key", required=True)
     list_parser.add_argument("--column", dest="columns", action="append", type=int, default=[])
     list_parser.add_argument("--columns-file")
+    list_parser.add_argument("--query")
+    list_parser.add_argument("--query-field", dest="query_fields", action="append", type=int, default=[])
+    list_parser.add_argument("--query-fields-file")
     list_parser.add_argument("--where-file")
     list_parser.add_argument("--order-by-file")
-    list_parser.add_argument("--limit", type=int, default=20)
     list_parser.add_argument("--page", type=int, default=1)
     list_parser.add_argument("--view-id")
     list_parser.add_argument("--list-type", dest="legacy_list_type", type=int, help=argparse.SUPPRESS)
@@ -72,11 +100,18 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     get.add_argument("--column", dest="columns", action="append", type=int, default=[])
     get.add_argument("--columns-file")
     get.add_argument("--view-id")
-    get.set_defaults(handler=_handle_get, format_hint="")
+    get.set_defaults(handler=_handle_get, format_hint="record_get")
+
+    logs = record_subparsers.add_parser("logs", help="读取单条记录全量日志并写入本地 JSONL")
+    logs.add_argument("--app-key", required=True)
+    logs.add_argument("--record-id", required=True)
+    logs.add_argument("--view-id")
+    logs.set_defaults(handler=_handle_logs, format_hint="record_logs")
 
     insert = record_subparsers.add_parser("insert", help="新增记录")
     insert.add_argument("--app-key", required=True)
-    insert.add_argument("--fields-file", required=True)
+    insert.add_argument("--fields-file", help=argparse.SUPPRESS)
+    insert.add_argument("--items-file")
     insert.add_argument("--verify-write", action=argparse.BooleanOptionalAction, default=True)
     insert.set_defaults(handler=_handle_insert, format_hint="")
 
@@ -95,7 +130,12 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     delete.add_argument("--record-ids-file")
     delete.set_defaults(handler=_handle_delete, format_hint="")
 
-    analyze = record_subparsers.add_parser("analyze", help="分析记录数据")
+    analyze = record_subparsers.add_parser("analyze", help=argparse.SUPPRESS)
+    record_subparsers._choices_actions = [  # type: ignore[attr-defined]
+        action
+        for action in record_subparsers._choices_actions  # type: ignore[attr-defined]
+        if getattr(action, "dest", None) != "analyze"
+    ]
     analyze.add_argument("--app-key", required=True)
     analyze.add_argument("--dimensions-file")
     analyze.add_argument("--metrics-file")
@@ -131,6 +171,13 @@ def _columns(args: argparse.Namespace) -> list[Any]:
     return columns
 
 
+def _query_fields(args: argparse.Namespace) -> list[Any]:
+    query_fields: list[Any] = list(getattr(args, "query_fields", None) or [])
+    if getattr(args, "query_fields_file", None):
+        query_fields.extend(require_list_arg(args.query_fields_file, option_name="--query-fields-file"))
+    return query_fields
+
+
 def _handle_schema_root(args: argparse.Namespace, _context: CliContext) -> dict:
     mode = (args.legacy_mode or "").strip()
     if mode:
@@ -188,6 +235,38 @@ def _handle_schema_code_block(args: argparse.Namespace, context: CliContext) ->
     return context.code_block.record_code_block_schema_get_public(profile=args.profile, app_key=args.app_key)
 
 
+def _candidate_context_fields(args: argparse.Namespace) -> dict[str, Any]:
+    return load_object_arg(args.fields_file, option_name="--fields-file") or {}
+
+
+def _handle_member_candidates(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.record.record_member_candidates(
+        profile=args.profile,
+        app_key=args.app_key,
+        field_id=args.field_id,
+        record_id=args.record_id,
+        workflow_node_id=args.workflow_node_id,
+        fields=_candidate_context_fields(args),
+        keyword=args.keyword,
+        page_num=args.page_num,
+        page_size=args.page_size,
+    )
+
+
+def _handle_department_candidates(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.record.record_department_candidates(
+        profile=args.profile,
+        app_key=args.app_key,
+        field_id=args.field_id,
+        record_id=args.record_id,
+        workflow_node_id=args.workflow_node_id,
+        fields=_candidate_context_fields(args),
+        keyword=args.keyword,
+        page_num=args.page_num,
+        page_size=args.page_size,
+    )
+
+
 def _validate_public_view_selector(
     *,
     view_id: str | None,
@@ -225,9 +304,10 @@ def _handle_list(args: argparse.Namespace, context: CliContext) -> dict:
         profile=args.profile,
         app_key=args.app_key,
         columns=_columns(args),
+        query=args.query,
+        query_fields=_query_fields(args),
         where=load_list_arg(args.where_file, option_name="--where-file"),
         order_by=load_list_arg(args.order_by_file, option_name="--order-by-file"),
-        limit=args.limit,
         page=args.page,
         view_id=args.view_id,
     )
@@ -254,7 +334,33 @@ def _handle_get(args: argparse.Namespace, context: CliContext) -> dict:
     )
 
 
+def _handle_logs(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.record.record_logs_get(
+        profile=args.profile,
+        app_key=args.app_key,
+        record_id=args.record_id,
+        view_id=args.view_id,
+    )
+
+
 def _handle_insert(args: argparse.Namespace, context: CliContext) -> dict:
+    if args.items_file:
+        if args.fields_file:
+            raise_config_error(
+                "record insert batch mode does not accept --fields-file.",
+                fix_hint="Use `record insert --app-key APP_KEY --items-file ITEMS.json` for batch inserts.",
+            )
+        return context.record.record_insert_public(
+            profile=args.profile,
+            app_key=args.app_key,
+            items=require_list_arg(args.items_file, option_name="--items-file"),
+            verify_write=bool(args.verify_write),
+        )
+    if not args.fields_file:
+        raise_config_error(
+            "record insert requires --items-file.",
+            fix_hint="Use `record insert --app-key APP_KEY --items-file ITEMS.json`; a single insert is one item in the JSON array.",
+        )
     return context.record.record_insert_public(
         profile=args.profile,
         app_key=args.app_key,

package/src/qingflow_mcp/cli/formatters.py

@@ -183,7 +183,17 @@ def _format_app_get(result: dict[str, Any]) -> str:
 def _format_record_list(result: dict[str, Any]) -> str:
     data = result.get("data") if isinstance(result.get("data"), dict) else {}
     items = data.get("items") if isinstance(data.get("items"), list) else []
-    lines = [f"Returned Records: {len(items)}"]
+    lines: list[str] = []
+    lookup = result.get("lookup") if isinstance(result.get("lookup"), dict) else {}
+    if lookup:
+        lines.append("Lookup:")
+        lines.append(f"- query: {lookup.get('query')}")
+        lines.append(f"- confidence: {lookup.get('confidence')}")
+        lines.append(f"- next_action: {lookup.get('next_action')}")
+        lines.append(f"- total_count: {lookup.get('total_count')}")
+        lines.append(f"- returned_count: {lookup.get('returned_count')}")
+        lines.append(f"- truncated: {lookup.get('truncated')}")
+    lines.append(f"Returned Records: {len(items)}")
     for item in items[:10]:
         if isinstance(item, dict):
             lines.append(json.dumps(item, ensure_ascii=False))
@@ -224,6 +234,95 @@ def _format_record_access(result: dict[str, Any]) -> str:
     return "\n".join(lines) + "\n"
 
 
+def _format_record_get(result: dict[str, Any]) -> str:
+    record = result.get("record") if isinstance(result.get("record"), dict) else {}
+    app = result.get("app") if isinstance(result.get("app"), dict) else {}
+    view = result.get("view") if isinstance(result.get("view"), dict) else {}
+    fields = result.get("fields") if isinstance(result.get("fields"), list) else []
+    data_logs = result.get("data_logs") if isinstance(result.get("data_logs"), dict) else {}
+    workflow_logs = result.get("workflow_logs") if isinstance(result.get("workflow_logs"), dict) else {}
+    media_assets = result.get("media_assets") if isinstance(result.get("media_assets"), dict) else {}
+    media_items = media_assets.get("items") if isinstance(media_assets.get("items"), list) else []
+    downloaded_media = [item for item in media_items if isinstance(item, dict) and item.get("access_status") == "downloaded"]
+    failed_media = [item for item in media_items if isinstance(item, dict) and item.get("access_status") != "downloaded"]
+    file_assets = result.get("file_assets") if isinstance(result.get("file_assets"), dict) else {}
+    file_items = file_assets.get("items") if isinstance(file_assets.get("items"), list) else []
+    downloaded_files = [item for item in file_items if isinstance(item, dict) and item.get("access_status") == "downloaded"]
+    failed_files = [item for item in file_items if isinstance(item, dict) and item.get("access_status") != "downloaded"]
+    extracted_files = [
+        item
+        for item in downloaded_files
+        if isinstance(item.get("extraction"), dict) and item["extraction"].get("status") == "ok"
+    ]
+    associated_resources = result.get("associated_resources") if isinstance(result.get("associated_resources"), list) else []
+    unavailable_context = result.get("unavailable_context") if isinstance(result.get("unavailable_context"), list) else []
+    lines = [
+        f"Status: {result.get('status') or '-'}",
+        f"App: {app.get('app_name') or app.get('app_key') or '-'} ({app.get('app_key') or '-'})",
+        f"View: {view.get('name') or view.get('view_id') or '-'}",
+        f"Record: {record.get('title') or '-'} ({record.get('record_id') or '-'})",
+        f"Fields: {len(fields)}",
+        f"Data logs: {data_logs.get('status') or '-'} / loaded={data_logs.get('items_loaded')}",
+        f"Workflow logs: {workflow_logs.get('status') or '-'} / loaded={workflow_logs.get('items_loaded')}",
+        f"Media assets: {media_assets.get('status') or '-'} / downloaded={len(downloaded_media)} / failed={len(failed_media)}",
+        f"File assets: {file_assets.get('status') or '-'} / downloaded={len(downloaded_files)} / extracted={len(extracted_files)} / failed={len(failed_files)}",
+        f"Associated resources: {len(associated_resources)}",
+        f"Unavailable contexts: {len(unavailable_context)}",
+    ]
+    if media_assets.get("local_dir"):
+        lines.append(f"Media dir: {media_assets.get('local_dir')}")
+    if file_assets.get("local_dir"):
+        lines.append(f"File dir: {file_assets.get('local_dir')}")
+    if failed_media:
+        failure_counts: dict[str, int] = {}
+        for item in failed_media:
+            key = f"{item.get('access_status') or 'unknown'} via {item.get('download_strategy') or 'unknown'}"
+            failure_counts[key] = failure_counts.get(key, 0) + 1
+        lines.append("Media failures: " + ", ".join(f"{key}={count}" for key, count in sorted(failure_counts.items())))
+    if failed_files:
+        failure_counts = {}
+        for item in failed_files:
+            key = f"{item.get('access_status') or 'unknown'} via {item.get('download_strategy') or 'unknown'}"
+            failure_counts[key] = failure_counts.get(key, 0) + 1
+        lines.append("File failures: " + ", ".join(f"{key}={count}" for key, count in sorted(failure_counts.items())))
+    summary = result.get("summary") if isinstance(result.get("summary"), dict) else {}
+    if summary.get("text"):
+        lines.append(f"Summary: {summary.get('text')}")
+    _append_warnings(lines, result.get("warnings"))
+    return "\n".join(lines) + "\n"
+
+
+def _format_record_logs(result: dict[str, Any]) -> str:
+    app = result.get("app") if isinstance(result.get("app"), dict) else {}
+    view = result.get("view") if isinstance(result.get("view"), dict) else {}
+    record = result.get("record") if isinstance(result.get("record"), dict) else {}
+    data_logs = result.get("data_logs") if isinstance(result.get("data_logs"), dict) else {}
+    workflow_logs = result.get("workflow_logs") if isinstance(result.get("workflow_logs"), dict) else {}
+    integrity = result.get("context_integrity") if isinstance(result.get("context_integrity"), dict) else {}
+    lines = [
+        f"Status: {result.get('status') or '-'}",
+        f"App: {app.get('app_name') or app.get('app_key') or '-'} ({app.get('app_key') or '-'})",
+        f"View: {view.get('name') or view.get('view_id') or '-'}",
+        f"Record: {record.get('title') or '-'} ({record.get('record_id') or '-'})",
+        f"Data logs: {data_logs.get('status') or '-'} / count={data_logs.get('items_count')} / pages={data_logs.get('pages_fetched')} / complete={data_logs.get('complete')}",
+        f"Workflow logs: {workflow_logs.get('status') or '-'} / count={workflow_logs.get('items_count')} / pages={workflow_logs.get('pages_fetched')} / complete={workflow_logs.get('complete')}",
+        f"Safe for full log conclusion: {integrity.get('safe_for_full_log_conclusion')}",
+    ]
+    if result.get("local_dir"):
+        lines.append(f"Local dir: {result.get('local_dir')}")
+    if data_logs.get("local_path"):
+        lines.append(f"Data logs file: {data_logs.get('local_path')}")
+    if workflow_logs.get("local_path"):
+        lines.append(f"Workflow logs file: {workflow_logs.get('local_path')}")
+    if result.get("summary_path"):
+        lines.append(f"Summary file: {result.get('summary_path')}")
+    _append_warnings(lines, result.get("warnings"))
+    unavailable = result.get("unavailable_context") if isinstance(result.get("unavailable_context"), list) else []
+    if unavailable:
+        lines.append(f"Unavailable contexts: {len(unavailable)}")
+    return "\n".join(lines) + "\n"
+
+
 def _format_task_list(result: dict[str, Any]) -> str:
     data = result.get("data") if isinstance(result.get("data"), dict) else {}
     items = data.get("items") if isinstance(data.get("items"), list) else []
@@ -720,10 +819,11 @@ _FORMATTERS = {
     "workspace_get": _format_workspace_get,
     "workspace_select": _format_workspace_select,
     "app_list": _format_app_items,
-    "app_search": _format_app_items,
     "app_get": _format_app_get,
     "record_list": _format_record_list,
     "record_access": _format_record_access,
+    "record_get": _format_record_get,
+    "record_logs": _format_record_logs,
     "task_list": _format_task_list,
     "task_workbench": _format_task_workbench,
     "task_get": _format_task_get,

package/src/qingflow_mcp/cli/main.py

@@ -8,6 +8,8 @@ from typing import Any, Callable, TextIO
 from ..errors import QingflowApiError
 from ..public_surface import cli_public_tool_spec_from_namespace
 from ..response_trim import resolve_cli_tool_name, trim_error_response, trim_public_response
+from ..tools.ai_builder_tools import _attach_builder_apply_envelope
+from ..version import get_cli_version, get_cli_version_info
 from .context import CliContext, build_cli_context
 from .formatters import emit_json_result, emit_text_result
 from .commands import register_all_commands
@@ -16,11 +18,27 @@ from .commands import register_all_commands
 Handler = Callable[[argparse.Namespace, CliContext], dict[str, Any]]
 
 
+class _CliArgumentError(Exception):
+    def __init__(self, *, prog: str, message: str, usage: str) -> None:
+        super().__init__(message)
+        self.prog = prog
+        self.message = message
+        self.usage = usage
+
+
+class _QingflowArgumentParser(argparse.ArgumentParser):
+    def error(self, message: str) -> None:
+        raise _CliArgumentError(prog=self.prog, message=message, usage=self.format_usage())
+
+
 def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog="qingflow", description="Qingflow CLI")
+    parser = _QingflowArgumentParser(prog="qingflow", description="Qingflow CLI")
     parser.add_argument("--profile", default="default", help="会话 profile，默认 default")
     parser.add_argument("--json", action="store_true", help="输出 JSON")
+    parser.add_argument("--version", action="store_true", help="输出 Qingflow CLI 版本")
     subparsers = parser.add_subparsers(dest="command", required=True)
+    version_parser = subparsers.add_parser("version", help="输出 Qingflow CLI 版本")
+    version_parser.set_defaults(handler=_handle_version, format_hint="version")
     register_all_commands(subparsers)
     return parser
 
@@ -40,19 +58,40 @@ def run(
     err = stderr or sys.stderr
     parser = build_parser()
     normalized_argv = _normalize_global_args(list(argv) if argv is not None else sys.argv[1:])
+    if "--version" in normalized_argv:
+        return _emit_version(json_mode=_should_force_json_output_argv_for_version(normalized_argv), stdout=out)
     try:
         args = parser.parse_args(normalized_argv)
+    except _CliArgumentError as exc:
+        if _should_force_json_output_argv(normalized_argv):
+            payload = {
+                "category": "config",
+                "status": "failed",
+                "error_code": "ARGUMENT_ERROR",
+                "message": exc.message,
+                "details": {"usage": exc.usage.strip(), "prog": exc.prog},
+            }
+            payload = _maybe_attach_builder_apply_error_envelope_from_argv(normalized_argv, payload)
+            emit_json_result(payload, stream=out)
+            return 2
+        err.write(exc.usage)
+        err.write(f"{exc.prog}: error: {exc.message}\n")
+        return 2
     except SystemExit as exc:
         return int(exc.code or 0)
     setattr(args, "_stdin", sys.stdin)
     setattr(args, "_stdout_stream", out)
     setattr(args, "_stderr_stream", err)
+    if getattr(args, "command", "") == "version":
+        return _emit_version(json_mode=bool(args.json), stdout=out)
     handler = getattr(args, "handler", None)
     if handler is None:
         parser.print_help(out)
         return 2
-    context = context_factory()
     try:
+        if _should_force_json_output(args):
+            setattr(args, "json", True)
+        context = context_factory()
         if not bool(args.json):
             _emit_cli_effective_context_notice(args, context, stream=err)
         result = handler(args, context)
@@ -60,12 +99,15 @@ def run(
         return int(exc.code or 0)
     except RuntimeError as exc:
         payload = trim_error_response(_parse_error_payload(exc))
+        payload = _maybe_attach_builder_apply_error_envelope_from_args(args, payload)
         return _emit_error(payload, json_mode=bool(args.json), stdout=out, stderr=err)
     except QingflowApiError as exc:
         payload = trim_error_response(exc.to_dict())
+        payload = _maybe_attach_builder_apply_error_envelope_from_args(args, payload)
         return _emit_error(payload, json_mode=bool(args.json), stdout=out, stderr=err)
     finally:
-        context.close()
+        if "context" in locals():
+            context.close()
 
     exit_code = _result_exit_code(result)
     trimmed_result = trim_public_response(resolve_cli_tool_name(args), result) if isinstance(result, dict) else result
@@ -87,6 +129,10 @@ def _normalize_global_args(argv: list[str]) -> list[str]:
             global_args.append(token)
             index += 1
             continue
+        if token == "--version":
+            global_args.append(token)
+            index += 1
+            continue
         if token == "--profile":
             global_args.append(token)
             if index + 1 >= len(argv):
@@ -104,6 +150,202 @@ def _normalize_global_args(argv: list[str]) -> list[str]:
     return global_args + remaining
 
 
+def _handle_version(_args: argparse.Namespace, _context: CliContext) -> dict[str, Any]:
+    info = get_cli_version_info()
+    return {
+        "ok": True,
+        "status": "success",
+        **info,
+    }
+
+
+def _emit_version(*, json_mode: bool, stdout: TextIO) -> int:
+    version = get_cli_version()
+    if json_mode:
+        emit_json_result(
+            {
+                "ok": True,
+                "status": "success",
+                **get_cli_version_info(),
+            },
+            stream=stdout,
+        )
+    else:
+        stdout.write(f"{version}\n")
+    return 0
+
+
+def _should_force_json_output_argv_for_version(argv: list[str]) -> bool:
+    return "--json" in argv
+
+
+def _should_force_json_output(args: argparse.Namespace) -> bool:
+    if bool(getattr(args, "force_json_output", False)):
+        return True
+    if (
+        getattr(args, "command", "") == "builder"
+        and getattr(args, "builder_app_command", "") == "repair-code-blocks"
+        and bool(getattr(args, "apply", False))
+    ):
+        return True
+    return False
+
+
+def _should_force_json_output_argv(argv: list[str]) -> bool:
+    tokens = _strip_global_args(argv)
+    if not tokens or tokens[0] not in {"builder", "build"}:
+        return False
+    if len(tokens) < 3:
+        return False
+    section = tokens[1]
+    action = tokens[2]
+    if section in {"package", "button", "associated-resource", "associated-resources", "portal", "schema", "layout", "views", "flow", "charts"}:
+        return action == "apply"
+    if section == "publish":
+        return action == "verify"
+    if section == "app":
+        if action == "release-edit-lock-if-mine":
+            return True
+        if action == "repair-code-blocks":
+            return "--apply" in tokens
+    return False
+
+
+def _maybe_attach_builder_apply_error_envelope_from_args(args: argparse.Namespace, payload: dict[str, Any]) -> dict[str, Any]:
+    operation = _builder_apply_operation_from_args(args)
+    if not operation:
+        return payload
+    enriched = dict(payload)
+    enriched.setdefault("status", "failed")
+    enriched.setdefault("ok", False)
+    enriched.setdefault("write_executed", False)
+    enriched.setdefault("safe_to_retry", False)
+    _copy_arg_identity(enriched, args)
+    return _attach_builder_apply_envelope(operation, enriched)
+
+
+def _maybe_attach_builder_apply_error_envelope_from_argv(argv: list[str], payload: dict[str, Any]) -> dict[str, Any]:
+    operation = _builder_apply_operation_from_argv(argv)
+    if not operation:
+        return payload
+    enriched = dict(payload)
+    enriched.setdefault("status", "failed")
+    enriched.setdefault("ok", False)
+    enriched.setdefault("write_executed", False)
+    enriched.setdefault("safe_to_retry", False)
+    _copy_argv_identity(enriched, argv)
+    return _attach_builder_apply_envelope(operation, enriched)
+
+
+def _builder_apply_operation_from_args(args: argparse.Namespace) -> str | None:
+    if getattr(args, "command", "") not in {"builder", "build"}:
+        return None
+    section = str(getattr(args, "builder_command", "") or "")
+    if section == "package" and getattr(args, "builder_package_command", "") == "apply":
+        return "package_apply"
+    if section == "button" and getattr(args, "builder_button_command", "") == "apply":
+        return "app_custom_buttons_apply"
+    if section in {"associated-resource", "associated-resources"} and getattr(args, "builder_associated_resource_command", "") == "apply":
+        return "app_associated_resources_apply"
+    if section == "portal" and getattr(args, "builder_portal_command", "") == "apply":
+        return "portal_apply"
+    if section == "schema" and getattr(args, "builder_schema_command", "") == "apply":
+        return "app_schema_apply"
+    if section == "layout" and getattr(args, "builder_layout_command", "") == "apply":
+        return "app_layout_apply"
+    if section == "views" and getattr(args, "builder_views_command", "") == "apply":
+        return "app_views_apply"
+    if section == "flow" and getattr(args, "builder_flow_command", "") == "apply":
+        return "app_flow_apply"
+    if section == "charts" and getattr(args, "builder_charts_command", "") == "apply":
+        return "app_charts_apply"
+    if section == "publish" and getattr(args, "builder_publish_command", "") == "verify":
+        return "app_publish_verify"
+    return None
+
+
+def _builder_apply_operation_from_argv(argv: list[str]) -> str | None:
+    tokens = _strip_global_args(argv)
+    if not tokens or tokens[0] not in {"builder", "build"} or len(tokens) < 3:
+        return None
+    section = tokens[1]
+    action = tokens[2]
+    if action != "apply" and not (section == "publish" and action == "verify"):
+        return None
+    mapping = {
+        "package": "package_apply",
+        "button": "app_custom_buttons_apply",
+        "associated-resource": "app_associated_resources_apply",
+        "associated-resources": "app_associated_resources_apply",
+        "portal": "portal_apply",
+        "schema": "app_schema_apply",
+        "layout": "app_layout_apply",
+        "views": "app_views_apply",
+        "flow": "app_flow_apply",
+        "charts": "app_charts_apply",
+        "publish": "app_publish_verify",
+    }
+    return mapping.get(section)
+
+
+def _copy_arg_identity(payload: dict[str, Any], args: argparse.Namespace) -> None:
+    for attr, key in (
+        ("app_key", "app_key"),
+        ("app_name", "app_name"),
+        ("app_title", "app_title"),
+        ("package_id", "package_id"),
+        ("dash_key", "dash_key"),
+        ("dash_name", "dash_name"),
+    ):
+        value = getattr(args, attr, None)
+        if value not in (None, ""):
+            payload.setdefault(key, value)
+
+
+def _copy_argv_identity(payload: dict[str, Any], argv: list[str]) -> None:
+    tokens = _strip_global_args(argv)
+    option_to_key = {
+        "--app-key": "app_key",
+        "--app-name": "app_name",
+        "--app-title": "app_title",
+        "--package-id": "package_id",
+        "--dash-key": "dash_key",
+        "--dash-name": "dash_name",
+    }
+    index = 0
+    while index < len(tokens):
+        token = tokens[index]
+        if token in option_to_key and index + 1 < len(tokens):
+            payload.setdefault(option_to_key[token], tokens[index + 1])
+            index += 2
+            continue
+        for option, key in option_to_key.items():
+            prefix = f"{option}="
+            if token.startswith(prefix):
+                payload.setdefault(key, token[len(prefix) :])
+                break
+        index += 1
+
+
+def _strip_global_args(argv: list[str]) -> list[str]:
+    stripped: list[str] = []
+    index = 0
+    while index < len(argv):
+        token = argv[index]
+        if token == "--json":
+            index += 1
+            continue
+        if token == "--profile":
+            index += 2
+            continue
+        if token.startswith("--profile="):
+            index += 1
+            continue
+        stripped.append(token)
+        index += 1
+    return stripped
+
+
 def _parse_error_payload(exc: RuntimeError) -> dict[str, Any]:
     raw = str(exc)
     try: