@josephyan/qingflow-app-builder-mcp 0.2.0-beta.7 → 0.2.0-beta.71

package/src/qingflow_mcp/cli/__init__.py

@@ -0,0 +1 @@
+__all__: list[str] = []

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

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+import argparse
+
+from . import app, auth, builder, imports, record, task, workspace
+
+
+def register_all_commands(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    auth.register(subparsers)
+    workspace.register(subparsers)
+    app.register(subparsers)
+    record.register(subparsers)
+    imports.register(subparsers)
+    task.register(subparsers)
+    builder.register(subparsers)

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

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import argparse
+
+from ..context import CliContext
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser("app", help="应用发现")
+    app_subparsers = parser.add_subparsers(dest="app_command", required=True)
+
+    list_parser = app_subparsers.add_parser("list", help="列出可见应用")
+    list_parser.set_defaults(handler=_handle_list, format_hint="app_list")
+
+    search = app_subparsers.add_parser("search", help="搜索应用")
+    search.add_argument("--keyword", default="")
+    search.add_argument("--page", type=int, default=1)
+    search.add_argument("--page-size", type=int, default=50)
+    search.set_defaults(handler=_handle_search, format_hint="app_search")
+
+    get = app_subparsers.add_parser("get", help="读取应用可访问视图与导入能力")
+    get.add_argument("--app-key", required=True)
+    get.set_defaults(handler=_handle_get, format_hint="app_get")
+
+
+def _handle_list(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.app.app_list(profile=args.profile)
+
+
+def _handle_search(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.app.app_search(
+        profile=args.profile,
+        keyword=args.keyword,
+        page_num=args.page,
+        page_size=args.page_size,
+    )
+
+
+def _handle_get(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.app.app_get(profile=args.profile, app_key=args.app_key)

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

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import argparse
+import getpass
+import sys
+
+from ...errors import QingflowApiError
+from ..context import CliContext
+from .common import read_secret_arg
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser("auth", help="认证与会话")
+    auth_subparsers = parser.add_subparsers(dest="auth_command", required=True)
+
+    login = auth_subparsers.add_parser("login", help="邮箱密码登录")
+    login.add_argument("--base-url")
+    login.add_argument("--qf-version")
+    login.add_argument("--email", required=True)
+    login.add_argument("--password")
+    login.add_argument("--password-stdin", action="store_true")
+    login.add_argument("--persist", action=argparse.BooleanOptionalAction, default=True)
+    login.set_defaults(handler=_handle_login, format_hint="auth_whoami")
+
+    use_token = auth_subparsers.add_parser("use-token", help="直接注入 token")
+    use_token.add_argument("--base-url")
+    use_token.add_argument("--qf-version")
+    use_token.add_argument("--token")
+    use_token.add_argument("--token-stdin", action="store_true")
+    use_token.add_argument("--ws-id", type=int)
+    use_token.add_argument("--persist", action=argparse.BooleanOptionalAction, default=False)
+    use_token.set_defaults(handler=_handle_use_token, format_hint="auth_whoami")
+
+    whoami = auth_subparsers.add_parser("whoami", help="查看当前登录态")
+    whoami.set_defaults(handler=_handle_whoami, format_hint="auth_whoami")
+
+    logout = auth_subparsers.add_parser("logout", help="退出登录")
+    logout.add_argument("--forget-persisted", action="store_true")
+    logout.set_defaults(handler=_handle_logout, format_hint="")
+
+
+def _handle_login(args: argparse.Namespace, context: CliContext) -> dict:
+    password = args.password
+    if args.password_stdin:
+        password = read_secret_arg(args.password, stdin_enabled=True, label="password")
+    elif not password:
+        if sys.stdin.isatty():
+            password = getpass.getpass("Password: ")
+        else:
+            raise QingflowApiError.config_error("password is required; use --password or --password-stdin")
+    return context.auth.auth_login(
+        profile=args.profile,
+        base_url=args.base_url,
+        qf_version=args.qf_version,
+        email=args.email,
+        password=password,
+        persist=bool(args.persist),
+    )
+
+
+def _handle_use_token(args: argparse.Namespace, context: CliContext) -> dict:
+    token = read_secret_arg(args.token, stdin_enabled=bool(args.token_stdin), label="token")
+    return context.auth.auth_use_token(
+        profile=args.profile,
+        base_url=args.base_url,
+        qf_version=args.qf_version,
+        token=token,
+        ws_id=args.ws_id,
+        persist=bool(args.persist),
+    )
+
+
+def _handle_whoami(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.auth.auth_whoami(profile=args.profile)
+
+
+def _handle_logout(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.auth.auth_logout(profile=args.profile, forget_persisted=bool(args.forget_persisted))

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

@@ -0,0 +1,515 @@
+from __future__ import annotations
+
+import argparse
+
+from ..context import CliContext
+from .common import load_list_arg, load_object_arg, raise_config_error, require_list_arg
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser("builder", aliases=["build"], help="稳定 builder 命令")
+    builder_subparsers = parser.add_subparsers(dest="builder_command", required=True)
+
+    contract = builder_subparsers.add_parser("contract", help="读取 builder tool 合约")
+    contract.add_argument("--tool-name", required=True)
+    contract.set_defaults(handler=_handle_contract, format_hint="builder_summary")
+
+    member = builder_subparsers.add_parser("member", help="成员目录")
+    member_subparsers = member.add_subparsers(dest="builder_member_command", required=True)
+    member_search = member_subparsers.add_parser("search", help="搜索成员")
+    member_search.add_argument("--query", default="")
+    member_search.add_argument("--page-num", type=int, default=1)
+    member_search.add_argument("--page-size", type=int, default=20)
+    member_search.add_argument("--contain-disable", action=argparse.BooleanOptionalAction, default=False)
+    member_search.set_defaults(handler=_handle_member_search, format_hint="builder_summary")
+
+    role = builder_subparsers.add_parser("role", help="角色目录")
+    role_subparsers = role.add_subparsers(dest="builder_role_command", required=True)
+    role_search = role_subparsers.add_parser("search", help="搜索角色")
+    role_search.add_argument("--keyword", default="")
+    role_search.add_argument("--page-num", type=int, default=1)
+    role_search.add_argument("--page-size", type=int, default=20)
+    role_search.set_defaults(handler=_handle_role_search, format_hint="builder_summary")
+
+    role_create = role_subparsers.add_parser("create", help="创建角色")
+    role_create.add_argument("--role-name", required=True)
+    role_create.add_argument("--member-uids-file")
+    role_create.add_argument("--member-emails-file")
+    role_create.add_argument("--member-names-file")
+    role_create.add_argument("--role-icon", default="ex-user-outlined")
+    role_create.set_defaults(handler=_handle_role_create, format_hint="builder_summary")
+
+    package = builder_subparsers.add_parser("package", help="应用包")
+    package_subparsers = package.add_subparsers(dest="builder_package_command", required=True)
+    package_list = package_subparsers.add_parser("list", help="列出应用包")
+    package_list.add_argument("--trial-status", default="all")
+    package_list.set_defaults(handler=_handle_package_list, format_hint="builder_summary")
+
+    package_resolve = package_subparsers.add_parser("resolve", help="解析应用包")
+    package_resolve.add_argument("--package-name", required=True)
+    package_resolve.set_defaults(handler=_handle_package_resolve, format_hint="builder_summary")
+
+    package_create = package_subparsers.add_parser("create", help="创建应用包")
+    package_create.add_argument("--package-name", required=True)
+    package_create.add_argument("--icon")
+    package_create.add_argument("--color")
+    package_create.set_defaults(handler=_handle_package_create, format_hint="builder_summary")
+
+    package_attach_app = package_subparsers.add_parser("attach-app", help="将应用挂载到应用包")
+    package_attach_app.add_argument("--tag-id", type=int, required=True)
+    package_attach_app.add_argument("--app-key", required=True)
+    package_attach_app.add_argument("--app-title", dest="legacy_app_title", help=argparse.SUPPRESS)
+    package_attach_app.set_defaults(handler=_handle_package_attach_app, format_hint="builder_summary")
+
+    app = builder_subparsers.add_parser("app", help="应用")
+    app_subparsers = app.add_subparsers(dest="builder_app_command", required=True)
+
+    app_resolve = app_subparsers.add_parser("resolve", help="解析应用")
+    app_resolve.add_argument("--app-key", default="")
+    app_resolve.add_argument("--app-name", default="")
+    app_resolve.add_argument("--package-tag-id", type=int)
+    app_resolve.set_defaults(handler=_handle_app_resolve, format_hint="builder_summary")
+
+    app_release_lock = app_subparsers.add_parser("release-edit-lock-if-mine", help="释放当前账号持有的编辑锁")
+    app_release_lock.add_argument("--app-key", required=True)
+    app_release_lock.add_argument("--lock-owner-email", required=True)
+    app_release_lock.add_argument("--lock-owner-name", required=True)
+    app_release_lock.set_defaults(handler=_handle_app_release_edit_lock_if_mine, format_hint="builder_summary")
+
+    button = builder_subparsers.add_parser("button", help="自定义按钮")
+    button_subparsers = button.add_subparsers(dest="builder_button_command", required=True)
+
+    button_list = button_subparsers.add_parser("list", help="列出自定义按钮")
+    button_list.add_argument("--app-key", required=True)
+    button_list.set_defaults(handler=_handle_button_list, format_hint="builder_summary")
+
+    button_get = button_subparsers.add_parser("get", help="读取自定义按钮")
+    button_get.add_argument("--app-key", required=True)
+    button_get.add_argument("--button-id", type=int, required=True)
+    button_get.set_defaults(handler=_handle_button_get, format_hint="builder_summary")
+
+    button_create = button_subparsers.add_parser("create", help="创建自定义按钮")
+    button_create.add_argument("--app-key", required=True)
+    button_create.add_argument("--payload-file", required=True)
+    button_create.set_defaults(handler=_handle_button_create, format_hint="builder_summary")
+
+    button_update = button_subparsers.add_parser("update", help="更新自定义按钮")
+    button_update.add_argument("--app-key", required=True)
+    button_update.add_argument("--button-id", type=int, required=True)
+    button_update.add_argument("--payload-file", required=True)
+    button_update.set_defaults(handler=_handle_button_update, format_hint="builder_summary")
+
+    button_delete = button_subparsers.add_parser("delete", help="删除自定义按钮")
+    button_delete.add_argument("--app-key", required=True)
+    button_delete.add_argument("--button-id", type=int, required=True)
+    button_delete.set_defaults(handler=_handle_button_delete, format_hint="builder_summary")
+
+    for name, help_text, handler in [
+        ("read-summary", "读取应用摘要", _handle_app_read_summary),
+        ("read-fields", "读取字段摘要", _handle_app_read_fields),
+        ("read-layout", "读取布局摘要", _handle_app_read_layout),
+        ("read-views", "读取视图摘要", _handle_app_read_views),
+        ("read-flow", "读取流程摘要", _handle_app_read_flow),
+        ("read-charts", "读取报表摘要", _handle_app_read_charts),
+    ]:
+        sub = app_subparsers.add_parser(name, help=help_text)
+        sub.add_argument("--app-key", required=True)
+        sub.set_defaults(handler=handler, format_hint="builder_summary")
+
+    portal = builder_subparsers.add_parser("portal", help="门户")
+    portal_subparsers = portal.add_subparsers(dest="builder_portal_command", required=True)
+    portal_list = portal_subparsers.add_parser("list", help="列出可访问门户")
+    portal_list.set_defaults(handler=_handle_portal_list, format_hint="builder_summary")
+
+    portal_get = portal_subparsers.add_parser("get", help="读取门户详情")
+    portal_get.add_argument("--dash-key", required=True)
+    portal_get.add_argument("--being-draft", action=argparse.BooleanOptionalAction, default=True)
+    portal_get.set_defaults(handler=_handle_portal_get, format_hint="builder_summary")
+
+    portal_read = portal_subparsers.add_parser("read-summary", help="读取门户摘要")
+    portal_read.add_argument("--dash-key", required=True)
+    portal_read.add_argument("--being-draft", action=argparse.BooleanOptionalAction, default=True)
+    portal_read.set_defaults(handler=_handle_portal_read_summary, format_hint="builder_summary")
+
+    portal_apply = portal_subparsers.add_parser("apply", help="更新门户")
+    portal_apply.add_argument("--dash-key", default="")
+    portal_apply.add_argument("--dash-name", default="")
+    portal_apply.add_argument("--package-tag-id", type=int)
+    portal_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=True)
+    portal_apply.add_argument("--sections-file", required=True)
+    portal_apply.add_argument("--auth-file")
+    portal_apply.add_argument("--icon")
+    portal_apply.add_argument("--color")
+    portal_apply.add_argument("--hide-copyright", action=argparse.BooleanOptionalAction, default=None)
+    portal_apply.add_argument("--dash-global-config-file")
+    portal_apply.add_argument("--config-file")
+    portal_apply.set_defaults(handler=_handle_portal_apply, format_hint="builder_summary")
+
+    schema_apply = builder_subparsers.add_parser("schema", help="字段搭建")
+    schema_apply_subparsers = schema_apply.add_subparsers(dest="builder_schema_command", required=True)
+    schema_apply_apply = schema_apply_subparsers.add_parser("apply", help="执行字段变更")
+    schema_apply_apply.add_argument("--app-key", default="")
+    schema_apply_apply.add_argument("--package-tag-id", type=int)
+    schema_apply_apply.add_argument("--app-name", default="")
+    schema_apply_apply.add_argument("--app-title", default="")
+    schema_apply_apply.add_argument("--icon")
+    schema_apply_apply.add_argument("--color")
+    schema_apply_apply.add_argument("--create-if-missing", action="store_true")
+    schema_apply_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=True)
+    schema_apply_apply.add_argument("--add-fields-file")
+    schema_apply_apply.add_argument("--update-fields-file")
+    schema_apply_apply.add_argument("--remove-fields-file")
+    schema_apply_apply.set_defaults(handler=_handle_schema_apply, format_hint="builder_summary")
+
+    layout_apply = builder_subparsers.add_parser("layout", help="布局")
+    layout_apply_subparsers = layout_apply.add_subparsers(dest="builder_layout_command", required=True)
+    layout_apply_apply = layout_apply_subparsers.add_parser("apply", help="执行布局变更")
+    layout_apply_apply.add_argument("--app-key", required=True)
+    layout_apply_apply.add_argument("--mode", choices=["merge", "replace"], default="merge")
+    layout_apply_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=True)
+    layout_apply_apply.add_argument("--sections-file", required=True)
+    layout_apply_apply.set_defaults(handler=_handle_layout_apply, format_hint="builder_summary")
+
+    views_apply = builder_subparsers.add_parser("views", help="视图")
+    views_apply_subparsers = views_apply.add_subparsers(dest="builder_views_command", required=True)
+    views_apply_apply = views_apply_subparsers.add_parser("apply", help="执行视图变更")
+    views_apply_apply.add_argument("--app-key", required=True)
+    views_apply_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=True)
+    views_apply_apply.add_argument("--upsert-views-file")
+    views_apply_apply.add_argument("--remove-views-file")
+    views_apply_apply.set_defaults(handler=_handle_views_apply, format_hint="builder_summary")
+
+    flow_apply = builder_subparsers.add_parser("flow", help="流程")
+    flow_apply_subparsers = flow_apply.add_subparsers(dest="builder_flow_command", required=True)
+    flow_apply_apply = flow_apply_subparsers.add_parser("apply", help="执行流程变更")
+    flow_apply_apply.add_argument("--app-key", required=True)
+    flow_apply_apply.add_argument("--mode", choices=["replace"], default="replace")
+    flow_apply_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=True)
+    flow_apply_apply.add_argument("--nodes-file", required=True)
+    flow_apply_apply.add_argument("--transitions-file", required=True)
+    flow_apply_apply.set_defaults(handler=_handle_flow_apply, format_hint="builder_summary")
+
+    charts_apply = builder_subparsers.add_parser("charts", help="报表")
+    charts_apply_subparsers = charts_apply.add_subparsers(dest="builder_charts_command", required=True)
+    charts_apply_apply = charts_apply_subparsers.add_parser("apply", help="执行报表变更")
+    charts_apply_apply.add_argument("--app-key", required=True)
+    charts_apply_apply.add_argument("--upsert-file")
+    charts_apply_apply.add_argument("--remove-chart-ids-file")
+    charts_apply_apply.add_argument("--reorder-chart-ids-file")
+    charts_apply_apply.set_defaults(handler=_handle_charts_apply, format_hint="builder_summary")
+
+    publish_verify = builder_subparsers.add_parser("publish", help="发布校验")
+    publish_verify_subparsers = publish_verify.add_subparsers(dest="builder_publish_command", required=True)
+    publish_verify_verify = publish_verify_subparsers.add_parser("verify", help="校验应用发布")
+    publish_verify_verify.add_argument("--app-key", required=True)
+    publish_verify_verify.add_argument("--expected-package-tag-id", type=int)
+    publish_verify_verify.set_defaults(handler=_handle_publish_verify, format_hint="builder_summary")
+
+    view = builder_subparsers.add_parser("view", help="视图详情")
+    view_subparsers = view.add_subparsers(dest="builder_view_command", required=True)
+    view_get = view_subparsers.add_parser("get", help="读取视图详情")
+    view_get.add_argument("--viewgraph-key", required=True)
+    view_get.set_defaults(handler=_handle_view_get, format_hint="builder_summary")
+
+    chart = builder_subparsers.add_parser("chart", help="报表详情")
+    chart_subparsers = chart.add_subparsers(dest="builder_chart_command", required=True)
+    chart_get = chart_subparsers.add_parser("get", help="读取报表详情和数据")
+    chart_get.add_argument("--chart-id", required=True)
+    chart_get.add_argument("--data-payload-file")
+    chart_get.add_argument("--page-num", type=int)
+    chart_get.add_argument("--page-size", type=int)
+    chart_get.add_argument("--page-num-y", type=int)
+    chart_get.add_argument("--page-size-y", type=int)
+    chart_get.set_defaults(handler=_handle_chart_get, format_hint="builder_summary")
+
+
+def _handle_package_list(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.package_list(profile=args.profile, trial_status=args.trial_status)
+
+
+def _handle_contract(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.builder_tool_contract(tool_name=args.tool_name)
+
+
+def _handle_member_search(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.member_search(
+        profile=args.profile,
+        query=args.query,
+        page_num=args.page_num,
+        page_size=args.page_size,
+        contain_disable=bool(args.contain_disable),
+    )
+
+
+def _handle_role_search(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.role_search(
+        profile=args.profile,
+        keyword=args.keyword,
+        page_num=args.page_num,
+        page_size=args.page_size,
+    )
+
+
+def _handle_role_create(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.role_create(
+        profile=args.profile,
+        role_name=args.role_name,
+        member_uids=load_list_arg(args.member_uids_file, option_name="--member-uids-file"),
+        member_emails=load_list_arg(args.member_emails_file, option_name="--member-emails-file"),
+        member_names=load_list_arg(args.member_names_file, option_name="--member-names-file"),
+        role_icon=args.role_icon,
+    )
+
+
+def _handle_package_resolve(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.package_resolve(profile=args.profile, package_name=args.package_name)
+
+
+def _handle_package_create(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.package_create(
+        profile=args.profile,
+        package_name=args.package_name,
+        icon=args.icon,
+        color=args.color,
+    )
+
+
+def _handle_package_attach_app(args: argparse.Namespace, context: CliContext) -> dict:
+    if (args.legacy_app_title or "").strip():
+        raise_config_error(
+            "package attach-app no longer accepts app_title.",
+            fix_hint="Use `--app-key` to identify the app to attach.",
+        )
+    return context.builder.package_attach_app(
+        profile=args.profile,
+        tag_id=args.tag_id,
+        app_key=args.app_key,
+    )
+
+
+def _handle_app_resolve(args: argparse.Namespace, context: CliContext) -> dict:
+    has_app_key = bool((args.app_key or "").strip())
+    has_app_name = bool((args.app_name or "").strip())
+    has_package_tag_id = args.package_tag_id is not None
+    if has_app_key and (has_app_name or has_package_tag_id):
+        raise_config_error(
+            "app resolve accepts exactly one selector mode.",
+            fix_hint="Use only `--app-key`, or use `--app-name` together with `--package-tag-id`.",
+        )
+    if not has_app_key and not (has_app_name and has_package_tag_id):
+        raise_config_error(
+            "app resolve requires either --app-key, or --app-name together with --package-tag-id.",
+            fix_hint="For an existing known app, pass `--app-key`. For package-scoped lookup, pass both `--app-name` and `--package-tag-id`.",
+        )
+    return context.builder.app_resolve(
+        profile=args.profile,
+        app_key=args.app_key,
+        app_name=args.app_name,
+        package_tag_id=args.package_tag_id,
+    )
+
+
+def _handle_app_release_edit_lock_if_mine(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_release_edit_lock_if_mine(
+        profile=args.profile,
+        app_key=args.app_key,
+        lock_owner_email=args.lock_owner_email,
+        lock_owner_name=args.lock_owner_name,
+    )
+
+
+def _handle_button_list(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_custom_button_list(profile=args.profile, app_key=args.app_key)
+
+
+def _handle_button_get(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_custom_button_get(profile=args.profile, app_key=args.app_key, button_id=args.button_id)
+
+
+def _handle_button_create(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_custom_button_create(
+        profile=args.profile,
+        app_key=args.app_key,
+        payload=load_object_arg(args.payload_file, option_name="--payload-file"),
+    )
+
+
+def _handle_button_update(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_custom_button_update(
+        profile=args.profile,
+        app_key=args.app_key,
+        button_id=args.button_id,
+        payload=load_object_arg(args.payload_file, option_name="--payload-file"),
+    )
+
+
+def _handle_button_delete(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_custom_button_delete(profile=args.profile, app_key=args.app_key, button_id=args.button_id)
+
+
+def _handle_app_read_summary(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_read_summary(profile=args.profile, app_key=args.app_key)
+
+
+def _handle_app_read_fields(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_read_fields(profile=args.profile, app_key=args.app_key)
+
+
+def _handle_app_read_layout(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_read_layout_summary(profile=args.profile, app_key=args.app_key)
+
+
+def _handle_app_read_views(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_read_views_summary(profile=args.profile, app_key=args.app_key)
+
+
+def _handle_app_read_flow(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_read_flow_summary(profile=args.profile, app_key=args.app_key)
+
+
+def _handle_app_read_charts(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_read_charts_summary(profile=args.profile, app_key=args.app_key)
+
+
+def _handle_portal_list(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.portal_list(profile=args.profile)
+
+
+def _handle_portal_get(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.portal_get(profile=args.profile, dash_key=args.dash_key, being_draft=bool(args.being_draft))
+
+
+def _handle_portal_read_summary(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.portal_read_summary(
+        profile=args.profile,
+        dash_key=args.dash_key,
+        being_draft=bool(args.being_draft),
+    )
+
+
+def _handle_view_get(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.view_get(profile=args.profile, viewgraph_key=args.viewgraph_key)
+
+
+def _handle_chart_get(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.chart_get(
+        profile=args.profile,
+        chart_id=args.chart_id,
+        data_payload=load_object_arg(args.data_payload_file, option_name="--data-payload-file") if args.data_payload_file else {},
+        page_num=args.page_num,
+        page_size=args.page_size,
+        page_num_y=args.page_num_y,
+        page_size_y=args.page_size_y,
+    )
+
+
+def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
+    has_app_key = bool((args.app_key or "").strip())
+    has_app_name = bool((args.app_name or "").strip())
+    has_app_title = bool((args.app_title or "").strip())
+    has_package_tag_id = args.package_tag_id is not None
+    if has_app_key:
+        if args.create_if_missing or has_app_name or has_package_tag_id or has_app_title:
+            raise_config_error(
+                "schema apply edit mode only accepts --app-key as the resource selector.",
+                fix_hint="For existing apps, pass `--app-key` only. For create mode, use `--package-tag-id --app-name --create-if-missing`.",
+            )
+    else:
+        if not args.create_if_missing or not has_package_tag_id or not has_app_name:
+            raise_config_error(
+                "schema apply create mode requires --package-tag-id, --app-name, and --create-if-missing.",
+                fix_hint="Use `--app-key` for existing apps, or pass `--package-tag-id --app-name --create-if-missing` to create a new app.",
+            )
+    return context.builder.app_schema_apply(
+        profile=args.profile,
+        app_key=args.app_key,
+        package_tag_id=args.package_tag_id,
+        app_name=args.app_name,
+        app_title=args.app_title,
+        icon=args.icon,
+        color=args.color,
+        create_if_missing=bool(args.create_if_missing),
+        publish=bool(args.publish),
+        add_fields=load_list_arg(args.add_fields_file, option_name="--add-fields-file"),
+        update_fields=load_list_arg(args.update_fields_file, option_name="--update-fields-file"),
+        remove_fields=load_list_arg(args.remove_fields_file, option_name="--remove-fields-file"),
+    )
+
+
+def _handle_layout_apply(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_layout_apply(
+        profile=args.profile,
+        app_key=args.app_key,
+        mode=args.mode,
+        publish=bool(args.publish),
+        sections=require_list_arg(args.sections_file, option_name="--sections-file"),
+    )
+
+
+def _handle_views_apply(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_views_apply(
+        profile=args.profile,
+        app_key=args.app_key,
+        publish=bool(args.publish),
+        upsert_views=load_list_arg(args.upsert_views_file, option_name="--upsert-views-file"),
+        remove_views=load_list_arg(args.remove_views_file, option_name="--remove-views-file"),
+    )
+
+
+def _handle_flow_apply(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_flow_apply(
+        profile=args.profile,
+        app_key=args.app_key,
+        mode=args.mode,
+        publish=bool(args.publish),
+        nodes=require_list_arg(args.nodes_file, option_name="--nodes-file"),
+        transitions=require_list_arg(args.transitions_file, option_name="--transitions-file"),
+    )
+
+
+def _handle_charts_apply(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_charts_apply(
+        profile=args.profile,
+        app_key=args.app_key,
+        upsert_charts=load_list_arg(args.upsert_file, option_name="--upsert-file"),
+        remove_chart_ids=load_list_arg(args.remove_chart_ids_file, option_name="--remove-chart-ids-file"),
+        reorder_chart_ids=load_list_arg(args.reorder_chart_ids_file, option_name="--reorder-chart-ids-file"),
+    )
+
+
+def _handle_portal_apply(args: argparse.Namespace, context: CliContext) -> dict:
+    has_dash_key = bool((args.dash_key or "").strip())
+    has_dash_name = bool((args.dash_name or "").strip())
+    has_package_tag_id = args.package_tag_id is not None
+    if has_dash_key and has_package_tag_id:
+        raise_config_error(
+            "portal apply accepts exactly one selector mode.",
+            fix_hint="Use `--dash-key` to update an existing portal, or use `--package-tag-id --dash-name` to create a new portal.",
+        )
+    if not has_dash_key and not (has_package_tag_id and has_dash_name):
+        raise_config_error(
+            "portal apply requires either --dash-key, or --package-tag-id together with --dash-name.",
+            fix_hint="Use `--dash-key` for an existing portal. For create mode, pass `--package-tag-id --dash-name`.",
+        )
+    return context.builder.portal_apply(
+        profile=args.profile,
+        dash_key=args.dash_key,
+        dash_name=args.dash_name,
+        package_tag_id=args.package_tag_id,
+        publish=bool(args.publish),
+        sections=require_list_arg(args.sections_file, option_name="--sections-file"),
+        auth=load_object_arg(args.auth_file, option_name="--auth-file"),
+        icon=args.icon,
+        color=args.color,
+        hide_copyright=args.hide_copyright,
+        dash_global_config=load_object_arg(args.dash_global_config_file, option_name="--dash-global-config-file"),
+        config=load_object_arg(args.config_file, option_name="--config-file"),
+    )
+
+
+def _handle_publish_verify(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_publish_verify(
+        profile=args.profile,
+        app_key=args.app_key,
+        expected_package_tag_id=args.expected_package_tag_id,
+    )