more progress on DaemonGoal API

src/python/pants/bsp/goal.py

@@ -12,16 +12,13 @@
 
 from pants.base.build_root import BuildRoot
 from pants.base.exiter import PANTS_FAILED_EXIT_CODE, PANTS_SUCCEEDED_EXIT_CODE, ExitCode
-from pants.base.specs import Specs
 from pants.bsp.context import BSPContext
 from pants.bsp.protocol import BSPConnection
 from pants.bsp.util_rules.lifecycle import BSP_VERSION, BSPLanguageSupport
-from pants.build_graph.build_configuration import BuildConfiguration
 from pants.engine.env_vars import CompleteEnvironmentVars
 from pants.engine.internals.session import SessionValues
 from pants.engine.unions import UnionMembership
-from pants.goal.builtin_goal import BuiltinGoal
-from pants.goal.daemon_goal import DaemonGoalContext
+from pants.goal.daemon_goal import DaemonGoal, DaemonGoalContext
 from pants.init.engine_initializer import GraphSession
 from pants.option.option_types import BoolOption, FileListOption, StrListOption
 from pants.option.option_value_container import OptionValueContainer

src/python/pants/build_graph/build_configuration.py

@@ -270,7 +270,7 @@ def register_remote_auth_plugin(self, remote_auth_plugin: Callable) -> None:
             self._remote_auth_plugin = remote_auth_plugin
 
         def register_daemon_goals(self, plugin_or_backend: str, daemon_goals: Iterable[type]):
-            """Registers the given builtin goals."""
+            """Registers the given daemon goals."""
             if not isinstance(daemon_goals, Iterable):
                 raise TypeError(
                     f"The entrypoint `daemon_goals` must return an iterable. "

src/python/pants/goal/daemon_goal.py

@@ -13,6 +13,7 @@
 from pants.engine.unions import UnionMembership
 from pants.init.engine_initializer import GraphSession
 from pants.option.options import Options
+from pants.option.scope import ScopeInfo
 
 
 @dataclass
@@ -23,20 +24,24 @@ class DaemonGoalContext:
     options: Options
     specs: Specs
     union_membership: UnionMembership
-    
+
 
 class DaemonGoal(ABC, GoalSubsystem):
-    """Configure a "daemon" goal which allows rules to "take over" Pants client execution.
+    """Configure a "daemon" goal which allows rules to "take over" Pants client execution in lieu
+    of executing an ordnary goal.
 
     Only a single daemon goal is executed per run, any remaining goals/arguments are passed
-    unaltered to the builtin goal. Daemon goals have precedence over regular goals.
+    unaltered to the daemon goal. Daemon goals have precedence over regular goals.
 
-    When multiple daemon goals are presented, the first builtin goal will be used unless there is a
+    When multiple daemon goals are presented, the first daemon goal will be used unless there is a
     daemon goal that begin with a hyphen (`-`), in which case the last such "option goal" will be
     prioritized. This is to support things like `./pants some-builtin-goal --help`.
+
+    The intended use for this API is rule code which runs a server (for example, a BSP server)
+    which provides an alternate interface to the Pants rule engine.
     """
 
-    # Used by `pants.option.arg_splitter.ArgSplitter()` to optionally allow aliasing builtin goals.
+    # Used by `pants.option.arg_splitter.ArgSplitter()` to optionally allow aliasing daemon goals.
     aliases: ClassVar[tuple[str, ...]] = ()
 
     @classmethod