pushmetrics-cli 0.1.0__py3-none-any.whl

pm/commands/_block_factory.py

@@ -0,0 +1,762 @@
+"""Factory for block-typed Click command groups (pm-tool plan §3.8).
+
+``make_block_group(name, block_type, *, crud_verbs, execute_verb, ...)`` returns
+a Click group exposing some subset of the standard block lifecycle:
+
+- ``get`` / ``list`` / ``create`` / ``update`` / ``delete`` — opt-in CRUD verbs
+- ``run`` / ``send`` — execute an existing block by uid OR atomic
+  create+execute from ``--stdin`` (today's ``run_sql --stdin`` ergonomic)
+- any number of *custom verbs* — direct-API ops that don't fit the standard
+  lifecycle (Tableau ``search``, metrics-view ``query``, slides
+  ``parse-template``, etc.)
+
+``block_type=None`` is the ``pm block`` plumbing case — ``--type X`` is
+required on commands that need a discriminator (create, run, send). When
+``block_type`` is bound (every domain group), the discriminator is implicit
+and the ``--type`` flag is hidden.
+
+One factory, no per-group conditionals. Every domain command file ends up
+as a single call to this function plus optional ``custom_verbs`` for the
+non-lifecycle operations. Adding a new block type later is data
+(a new domain command file), not new factory code.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, Dict, Optional
+
+import click
+
+from pm._alias import AliasedGroup
+from pm.client import PMClient
+from pm.errors import PMError, emit_error
+from pm.commands._helpers import (
+    confirm_delete,
+    json_option,
+    limit_option,
+    name_filter_option,
+    peek_name,
+    report_deleted,
+    select_rows,
+    yes_option,
+)
+from pm.output import emit
+from pm.types import CANONICAL_TYPES, canonicalize_type
+from pm.validators import normalize_content_json, validate_content_json
+
+
+# ── Constants ─────────────────────────────────────────────────────────
+
+CRUD_VERBS = ("get", "list", "create", "update", "delete")
+EXECUTE_VERBS = ("run", "send")
+_LIST_COLUMNS = (
+    ("UID", "uid"),
+    ("TYPE", "type"),
+    ("NAME", lambda r: r.get("verbose_name") or r.get("name") or ""),
+)
+
+
+# ── Decorators ────────────────────────────────────────────────────────
+
+
+# Display names for help text: article + name, so generated strings read
+# "an email block", "an SFTP block", "a chart (Plotly) block".
+_DISPLAY: Dict[str, tuple] = {
+    "sql": ("a", "SQL"),
+    "email": ("an", "email"),
+    "slack": ("a", "Slack"),
+    "sftp": ("an", "SFTP"),
+    "plotly": ("a", "chart (Plotly)"),
+    "explore": ("an", "explore"),
+    "metrics_view": ("a", "metrics view"),
+    "tableau": ("a", "Tableau view"),
+    "google_slides": ("a", "Google Slides"),
+}
+
+
+def _a_block(block_type: str) -> str:
+    article, name = _DISPLAY.get(block_type, ("a", block_type))
+    return f"{article} {name} block"
+
+
+def _blocks(block_type: str) -> str:
+    return f"{_DISPLAY.get(block_type, ('a', block_type))[1]} blocks"
+
+
+# ── Helpers ───────────────────────────────────────────────────────────
+
+
+def _read_stdin_json() -> Dict[str, Any]:
+    """Read all of stdin and parse it as a JSON object.
+
+    Surfaces ``PMError(argv_invalid)`` for empty input or non-object JSON
+    so the agent gets a structured envelope it can recover from. Reserved
+    for ``--stdin`` paths; flag-based bodies use ``parse_data``.
+    """
+    raw = sys.stdin.read()
+    if not raw.strip():
+        raise PMError(
+            error_code="argv_invalid",
+            message="--stdin set but stdin was empty",
+            help="pm help block",
+        )
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise PMError(
+            error_code="argv_invalid",
+            message=f"--stdin: invalid JSON ({exc.msg})",
+            received=raw[:120],
+            help="pm help block",
+        )
+    if not isinstance(parsed, dict):
+        raise PMError(
+            error_code="argv_invalid",
+            message=f"--stdin body must be a JSON object, got {type(parsed).__name__}",
+            received=type(parsed).__name__,
+            help="pm help block",
+        )
+    return parsed
+
+
+def _resolve_type(
+    bound: Optional[str],
+    flag: Optional[str],
+    *,
+    verb: str,
+) -> str:
+    """Pick the block type for a generated command.
+
+    A group built with ``block_type='sql'`` always uses ``'sql'`` and
+    ignores the ``--type`` flag (it's hidden on those groups anyway). A
+    plumbing group (``block_type=None``) requires ``--type X``; X is
+    canonicalized via :mod:`pm.types` so silent aliases (``query``,
+    ``plot``, ``chart``) and case-different inputs resolve correctly.
+    """
+    if bound is not None:
+        return bound
+    if not flag:
+        raise PMError(
+            error_code="argv_invalid",
+            message=f"`pm block {verb}` requires --type",
+            allowed=sorted(CANONICAL_TYPES),
+            help="pm help block",
+        )
+    return canonicalize_type(flag)
+
+
+def _client(ctx: click.Context) -> PMClient:
+    return PMClient.from_profile(ctx.obj["profile"])
+
+
+# ── Generated command bodies (private — called by factory subcommands) ─
+
+
+def _do_get(ctx: click.Context, uid: str) -> None:
+    client = _client(ctx)
+    block = client.blocks.get(uid)
+    client.persist()
+    emit(block, json_output=ctx.obj["json"])
+
+
+def _do_list(
+    ctx: click.Context,
+    *,
+    bound_type: Optional[str],
+    type_flag: Optional[str],
+    name_filter: Optional[str] = None,
+    limit: Optional[int] = None,
+) -> None:
+    type_filter = bound_type
+    if type_filter is None and type_flag:
+        try:
+            type_filter = canonicalize_type(type_flag)
+        except PMError as err:
+            emit_error(err)
+    client = _client(ctx)
+    items = select_rows(
+        client.blocks.list(type=type_filter),
+        name=name_filter,
+        fields=("name", "verbose_name"),
+        limit=limit,
+    )
+    client.persist()
+    emit(items, json_output=ctx.obj["json"], columns=_LIST_COLUMNS)
+
+
+def _do_create(
+    ctx: click.Context,
+    *,
+    bound_type: Optional[str],
+    type_flag: Optional[str],
+    name: str,
+    verbose_name: Optional[str],
+    use_stdin: bool,
+) -> None:
+    try:
+        block_type = _resolve_type(bound_type, type_flag, verb="create")
+        if not use_stdin:
+            raise PMError(
+                error_code="argv_invalid",
+                message="`create` requires --stdin (content_json body)",
+                help=f"pm help {block_type}",
+            )
+        body = _read_stdin_json()
+        validate_content_json(block_type, body, mode="create")
+    except PMError as err:
+        emit_error(err)
+    # Translate user-facing keys (body/message/channels-as-str) to the
+    # backend keys (value/value_markdown/channels-as-list) the worker
+    # reads. Codex review pass 2 fix.
+    body = normalize_content_json(block_type, body)
+    client = _client(ctx)
+    block = client.blocks.create(
+        type=block_type,
+        name=name,
+        content_json=body,
+        verbose_name=verbose_name,
+    )
+    client.persist()
+    emit(block, json_output=ctx.obj["json"])
+
+
+def _do_update(
+    ctx: click.Context,
+    uid: str,
+    *,
+    name: Optional[str],
+    verbose_name: Optional[str],
+    use_stdin: bool,
+) -> None:
+    content_json: Any = None
+    if use_stdin:
+        try:
+            content_json = _read_stdin_json()
+        except PMError as err:
+            emit_error(err)
+    if content_json is None and name is None and verbose_name is None:
+        raise click.ClickException(
+            "Nothing to update; pass --stdin, --name, or --verbose-name.",
+        )
+    # Update path: fetch the block to learn its type, then translate
+    # user-facing keys to backend keys. Without this, `pm sql update
+    # <uid> --stdin <<< '{"body": "x"}'` for an email block would
+    # persist `body` instead of `value` and the next run would send an
+    # empty body. Codex review pass 2 fix.
+    if content_json is not None:
+        client_for_type = _client(ctx)
+        current = client_for_type.blocks.get(uid)
+        if current.type:
+            content_json = normalize_content_json(current.type, content_json)
+
+    client = _client(ctx)
+    block = client.blocks.update(
+        uid,
+        content_json=content_json,
+        name=name,
+        verbose_name=verbose_name,
+    )
+    client.persist()
+    emit(block, json_output=ctx.obj["json"])
+
+
+def _do_delete(ctx: click.Context, uid: str, *, yes: bool) -> None:
+    if not yes:
+        # Same pattern as `pm reports delete` — show a verifiable name in
+        # the prompt instead of a bare hashid.
+        label = peek_name(lambda: _client(ctx).blocks.get(uid), "verbose_name", "name")
+        confirm_delete("block", uid, label)
+    client = _client(ctx)
+    client.blocks.delete(uid)
+    client.persist()
+    report_deleted(ctx, "block", uid)
+
+
+def _do_results(
+    ctx: click.Context,
+    uid: str,
+    *,
+    last: bool,
+    result_id: Optional[str],
+) -> None:
+    if last and result_id:
+        raise click.ClickException("Pass --last OR --result-id, not both.")
+    rid = "last_result" if last else result_id
+    client = _client(ctx)
+    payload = client.blocks.results(uid, result_id=rid)
+    client.persist()
+    emit(payload, json_output=ctx.obj["json"])
+
+
+def _do_execute(
+    ctx: click.Context,
+    uid: Optional[str],
+    *,
+    verb: str,
+    bound_type: Optional[str],
+    type_flag: Optional[str],
+    use_stdin: bool,
+    group: str = "block",
+) -> None:
+    help_topic = f"pm help {group}"
+    # Mixed uid + --stdin: the contract is one or the other (codex R4 #5).
+    try:
+        if uid and use_stdin:
+            raise PMError(
+                error_code="argv_invalid",
+                message=(
+                    "Pass <uid> OR --stdin, not both. "
+                    "<uid> runs an existing block; --stdin runs a transient "
+                    "override against an assigned scratch block."
+                ),
+                help=help_topic,
+            )
+        if not uid and not use_stdin:
+            raise PMError(
+                error_code="argv_invalid",
+                message=f"`{verb}` needs either <uid> or --stdin",
+                help=help_topic,
+            )
+        # When running an existing block by uid, the stored block.type is
+        # authoritative — silently accepting --type would let a stale or
+        # mistaken override hide a real type mismatch (e.g. a user thinks
+        # they're running a sql block but the uid actually belongs to an
+        # email block). Force the operator to remove the flag.
+        if uid and type_flag:
+            raise PMError(
+                error_code="argv_invalid",
+                message=(
+                    f"`{verb} <uid>` ignores --type; the block's stored type "
+                    f"is authoritative. Remove --type, or use `--stdin` "
+                    f"(without <uid>) to {verb} a transient override "
+                    f"against an assigned scratch block of the specified type."
+                ),
+                received=f"--type={type_flag!r}",
+                help=help_topic,
+            )
+
+        if uid:
+            client = _client(ctx)
+            result = client.blocks.execute_existing(uid, verb=verb)
+            client.persist()
+            emit(result, json_output=ctx.obj["json"])
+            return
+
+        # --stdin path: validate body against the bound or --type-provided
+        # type. The body is the transient content_json override applied to
+        # an assigned scratch block of `block_type` — no new persisted
+        # block. Mirrors the legacy ``run_sql`` agent tool.
+        block_type = _resolve_type(bound_type, type_flag, verb=verb)
+        body = _read_stdin_json()
+        validate_content_json(block_type, body, mode="create")
+    except PMError as err:
+        emit_error(err)
+
+    # Translate user-facing keys to backend keys (same as the regular
+    # create path — codex review pass 2 fix).
+    body = normalize_content_json(block_type, body)
+
+    client = _client(ctx)
+    result = client.blocks.execute_against_scratch(
+        block_type=block_type,
+        content_json=body,
+        verb=verb,
+    )
+    client.persist()
+    emit(result, json_output=ctx.obj["json"])
+
+
+# ── Subcommand constructors ────────────────────────────────────────────
+
+
+def _make_get() -> click.Command:
+    @click.command(name="get")
+    @click.argument("uid")
+    @json_option
+    @click.pass_context
+    def get(ctx: click.Context, uid: str) -> None:
+        """Show one block (full JSON in --json mode)."""
+        _do_get(ctx, uid)
+    return get
+
+
+def _make_list(block_type: Optional[str]) -> click.Command:
+    # Plumbing groups expose --type; bound groups hide it (the filter is implicit).
+    if block_type is None:
+        @click.command(name="list")
+        @click.option("--type", "type_flag", default=None,
+                      help="Filter by block type (e.g. sql, email, plotly).")
+        @name_filter_option(matches="name or display name")
+        @limit_option
+        @json_option
+        @click.pass_context
+        def list_(
+            ctx: click.Context,
+            type_flag: Optional[str],
+            name_filter: Optional[str],
+            limit: Optional[int],
+        ) -> None:
+            """List blocks in the current workspace."""
+            _do_list(ctx, bound_type=None, type_flag=type_flag, name_filter=name_filter, limit=limit)
+        return list_
+
+    @click.command(name="list")
+    @name_filter_option(matches="name or display name")
+    @limit_option
+    @json_option
+    @click.pass_context
+    def list_(ctx: click.Context, name_filter: Optional[str], limit: Optional[int]) -> None:
+        _do_list(ctx, bound_type=block_type, type_flag=None, name_filter=name_filter, limit=limit)
+    list_.help = f"List {_blocks(block_type)} in the current workspace."
+    return list_
+
+
+def _make_create(
+    block_type: Optional[str],
+    *,
+    create_has_side_effect: bool,
+    custom_help: Optional[str],
+) -> click.Command:
+    bound = block_type
+
+    @click.command(name="create")
+    @click.option("--name", required=True, help="Block name.")
+    @click.option("--verbose-name", default=None,
+                  help="Display name shown in the app (defaults to --name).")
+    @click.option("--stdin", "use_stdin", is_flag=True,
+                  help="Read the JSON body from stdin. Shape: the block's content fields (see pm help <group>).")
+    @click.option(
+        "--type", "type_flag", default=None,
+        hidden=bound is not None,
+        help="Block type (sql, email, plotly, ...).",
+    )
+    @json_option
+    @click.pass_context
+    def create(
+        ctx: click.Context,
+        name: str,
+        verbose_name: Optional[str],
+        use_stdin: bool,
+        type_flag: Optional[str],
+    ) -> None:
+        _do_create(
+            ctx,
+            bound_type=bound,
+            type_flag=type_flag,
+            name=name,
+            verbose_name=verbose_name,
+            use_stdin=use_stdin,
+        )
+
+    if custom_help:
+        create.help = custom_help
+    elif create_has_side_effect:
+        create.help = (
+            f"Create {_a_block(bound)} and render it.\n\n"
+            "Creating this block type also renders it once; the result is "
+            "available with results <uid> --last."
+        )
+    else:
+        create.help = (
+            f"Create {_a_block(bound)} without running it."
+            if bound is not None
+            else (
+                "Create a block of any type without running it.\n\n"
+                "--type is required here; the typed groups (pm sql, pm email, "
+                "...) set it for you."
+            )
+        )
+    return create
+
+
+def _make_update() -> click.Command:
+    @click.command(name="update")
+    @click.argument("uid")
+    @click.option("--name", default=None, help="Rename the block.")
+    @click.option("--verbose-name", default=None, help="Change the display name.")
+    @click.option("--stdin", "use_stdin", is_flag=True,
+                  help="Read the JSON body from stdin. Replaces the block's content fields.")
+    @json_option
+    @click.pass_context
+    def update(
+        ctx: click.Context,
+        uid: str,
+        name: Optional[str],
+        verbose_name: Optional[str],
+        use_stdin: bool,
+    ) -> None:
+        """Update editable fields on an existing block.
+
+        At least one of --stdin, --name, or --verbose-name must be passed.
+        """
+        _do_update(
+            ctx,
+            uid,
+            name=name,
+            verbose_name=verbose_name,
+            use_stdin=use_stdin,
+        )
+    return update
+
+
+def _make_delete() -> click.Command:
+    @click.command(name="delete")
+    @click.argument("uid")
+    @yes_option
+    @json_option
+    @click.pass_context
+    def delete(ctx: click.Context, uid: str, yes: bool) -> None:
+        """Delete a block."""
+        _do_delete(ctx, uid, yes=yes)
+    return delete
+
+
+def _make_results() -> click.Command:
+    """`<group> results <uid>` — fetch past execution result(s) for a block.
+
+    Auto-injected by `make_block_group` on every group whose `execute_verb`
+    is set (results only make sense for blocks that execute). Block-type-
+    agnostic: same logic regardless of group, because the backend's
+    `/results/` endpoint normalizes across the `query` (SQL) and
+    `block_execution` (every other type) underlying tables.
+    """
+    @click.command(name="results")
+    @click.argument("uid")
+    @click.option(
+        "--last",
+        is_flag=True,
+        help=(
+            "Fetch only the most recent result. Shorthand for "
+            "`--result-id last_result`. Mutually exclusive with --result-id."
+        ),
+    )
+    @click.option(
+        "--result-id",
+        default=None,
+        help=(
+            "Fetch one specific result by id. Without --last or this flag, "
+            "returns the list of recent results (backend caps ~10)."
+        ),
+    )
+    @json_option
+    @click.pass_context
+    def results(
+        ctx: click.Context,
+        uid: str,
+        last: bool,
+        result_id: Optional[str],
+    ) -> None:
+        """Show past execution result(s) for this block.
+
+        Use --last (or --result-id last_result) to get the most recent
+        payload — the typical follow-up to `<group> run`. Default (no
+        flags) returns the recent-results list with metadata only.
+        """
+        _do_results(ctx, uid, last=last, result_id=result_id)
+    return results
+
+
+def make_execute_subcommand(
+    verb: str,
+    block_type: Optional[str],
+    *,
+    custom_help: Optional[str] = None,
+    group: str = "block",
+) -> click.Command:
+    """Return a Click command for `run` / `send`.
+
+    With <uid>: hits BlocksClient.execute_existing(uid, verb=verb).
+    With --stdin (and bound or --type-provided block_type): hits
+    BlocksClient.execute_against_scratch(block_type=..., content_json=...,
+    verb=verb) — finds an assigned scratch block of the type, runs with
+    the body as a transient content_json override. Mirrors the legacy
+    ``run_sql`` / ``send_email`` agent tools — no new block is persisted.
+    Mixed (uid + --stdin): structured error envelope (codex R4 #5).
+
+    Exposed standalone for groups that want to bolt execute on without
+    going through ``make_block_group`` — none today, but the symmetry
+    matches the §3.8 spec.
+    """
+    if verb not in EXECUTE_VERBS:
+        raise ValueError(
+            f"make_execute_subcommand: verb must be 'run' or 'send', got {verb!r}"
+        )
+    bound = block_type
+
+    @click.command(name=verb)
+    @click.argument("uid", required=False)
+    @click.option("--stdin", "use_stdin", is_flag=True,
+                  help=(
+                      f"Read the JSON body from stdin and {verb} it once "
+                      "without saving a block."
+                  ))
+    @click.option(
+        "--type", "type_flag", default=None,
+        hidden=bound is not None,
+        help="Block type (sql, email, plotly, ...).",
+    )
+    @json_option
+    @click.pass_context
+    def cmd(
+        ctx: click.Context,
+        uid: Optional[str],
+        use_stdin: bool,
+        type_flag: Optional[str],
+    ) -> None:
+        _do_execute(
+            ctx,
+            uid,
+            verb=verb,
+            bound_type=bound,
+            type_flag=type_flag,
+            use_stdin=use_stdin,
+            group=group,
+        )
+
+    if custom_help:
+        cmd.help = custom_help
+    else:
+        action = "Run" if verb == "run" else "Send"
+        what = _a_block(bound) if bound is not None else "a block of any type"
+        cmd.help = (
+            f"{action} {what}.\n\n"
+            f"Pass UID to {verb} a saved block, or --stdin to {verb} a JSON "
+            f"body once without saving it"
+            + ("" if bound is not None else " (--type required)")
+            + "."
+        )
+    return cmd
+
+
+# ── Public entrypoint ─────────────────────────────────────────────────
+
+
+def make_block_group(
+    name: str,
+    block_type: Optional[str] = None,
+    *,
+    crud_verbs: tuple[str, ...] = (),
+    execute_verb: Optional[str] = None,
+    create_has_side_effect: bool = False,
+    custom_verbs: Optional[Dict[str, click.Command]] = None,
+    verb_help: Optional[Dict[str, str]] = None,
+    help_text: Optional[str] = None,
+) -> click.Group:
+    """Build a Click group for a block-typed CLI surface.
+
+    Args:
+        name: group name (``"sql"``, ``"email"``, ``"block"``, etc.).
+        block_type: bound block type for domain groups, or ``None`` for
+            plumbing (``pm block``), where ``--type`` is required on
+            create / run / send.
+        crud_verbs: subset of ``CRUD_VERBS`` (``"get"``, ``"list"``,
+            ``"create"``, ``"update"``, ``"delete"``).
+        execute_verb: ``"run"``, ``"send"``, or ``None`` (no execute).
+            Groups have at most one — execute semantics are unambiguous
+            per group.
+        create_has_side_effect: only changes the ``create`` help text
+            (currently used for ``plotly``, where create auto-renders the
+            PNG as a side effect — plan §3.0 carve-out).
+        custom_verbs: optional ``{verb_name: click.Command}`` mapping for
+            direct-API operations that don't fit the standard lifecycle
+            (Tableau ``search``, metrics-view ``query``, slides
+            ``parse-template`` / ``batch-update`` / ``export``).
+        verb_help: optional ``{verb: help_text}`` mapping that overrides
+            the factory-generated help string per verb. Used for the
+            documented exceptions (codex R3 #6 — tableau ``run`` must
+            start with "Exports/downloads a Tableau view ...").
+        help_text: group-level docstring shown by ``pm <group> --help``.
+
+    Returns:
+        A ``click.Group`` (``AliasedGroup`` subclass; ``ls`` aliases to
+        ``list``) with the requested verbs registered. Adding more
+        commands later is just ``group.add_command(cmd, name=...)``.
+    """
+    invalid_crud = [v for v in crud_verbs if v not in CRUD_VERBS]
+    if invalid_crud:
+        raise ValueError(
+            f"make_block_group({name!r}): unknown crud_verbs {invalid_crud!r}; "
+            f"must be a subset of {CRUD_VERBS}"
+        )
+    if execute_verb is not None and execute_verb not in EXECUTE_VERBS:
+        raise ValueError(
+            f"make_block_group({name!r}): execute_verb must be 'run', 'send', "
+            f"or None; got {execute_verb!r}"
+        )
+
+    overrides = verb_help or {}
+
+    @click.group(
+        name=name,
+        cls=AliasedGroup,
+        aliases={"ls": "list"},
+    )
+    def group() -> None:
+        pass
+
+    group.help = help_text or (
+        "Blocks of any type."
+        if block_type is None
+        else f"{_blocks(block_type)[0].upper()}{_blocks(block_type)[1:]}.\n\nBlock type: {block_type}."
+    )
+
+    if "get" in crud_verbs:
+        cmd = _make_get()
+        cmd.help = overrides.get("get", cmd.help)
+        group.add_command(cmd)
+    if "list" in crud_verbs:
+        cmd = _make_list(block_type)
+        cmd.help = overrides.get("list", cmd.help)
+        group.add_command(cmd)
+    if "create" in crud_verbs:
+        cmd = _make_create(
+            block_type,
+            create_has_side_effect=create_has_side_effect,
+            custom_help=overrides.get("create"),
+        )
+        group.add_command(cmd)
+    if "update" in crud_verbs:
+        cmd = _make_update()
+        cmd.help = overrides.get("update", cmd.help)
+        group.add_command(cmd)
+    if "delete" in crud_verbs:
+        cmd = _make_delete()
+        cmd.help = overrides.get("delete", cmd.help)
+        group.add_command(cmd)
+
+    if execute_verb is not None:
+        group.add_command(
+            make_execute_subcommand(
+                execute_verb,
+                block_type,
+                custom_help=overrides.get(execute_verb),
+                group=name,
+            ),
+        )
+        # `results` is the natural follow-up to `run`/`send` — auto-inject
+        # so `pm sql results <uid>`, `pm email results <uid>`, etc. all
+        # work without each domain file having to wire it explicitly.
+        # Groups without execute_verb (explore today) don't get results
+        # because there's no execution history to fetch.
+        results_cmd = _make_results()
+        results_cmd.help = overrides.get("results", results_cmd.help)
+        group.add_command(results_cmd)
+
+    if custom_verbs:
+        for verb_name, cmd in custom_verbs.items():
+            if verb_name in CRUD_VERBS or verb_name in EXECUTE_VERBS:
+                raise ValueError(
+                    f"make_block_group({name!r}): custom_verb {verb_name!r} "
+                    f"collides with a standard lifecycle verb; rename it."
+                )
+            if verb_name == "results":
+                raise ValueError(
+                    f"make_block_group({name!r}): custom_verb 'results' "
+                    f"collides with the auto-injected results verb; remove "
+                    f"the custom_verb entry (results is included automatically "
+                    f"on every group with execute_verb set)."
+                )
+            group.add_command(cmd, name=verb_name)
+
+    return group