feat(cli): let external packages add nooa subcommands via entry points

`nooa_cli.commands` discovered commands by scanning only its own directory,
so nothing outside this repo could add a `nooa` subcommand. Packages that
wanted to extend the CLI had to ship standalone console scripts instead,
changing the command name for every user.

Split `discover_commands()` into the existing built-in scan plus a new pass
over the `nooa_cli.commands` entry-point group, mirroring the existing
`nooa.skills` and `nooa.bundled_configs` groups:

    [project.entry-points."nooa_cli.commands"]
    tui = "my_package.cli.tui:command"

Built-ins are yielded first and win name collisions, so a third party cannot
shadow `eval` or `config`; each name is yielded exactly once. Every plugin
failure — broken distribution metadata, an entry point that fails to import,
or one resolving to a non-`click.Command` — is logged at WARNING and skipped,
since these are arbitrary third-party imports and must never make `nooa`
unusable. The built-in scan deliberately keeps raising `TypeError`: that is a
bug in this repo and should be loud. Plugins are sorted by entry-point name so
`nooa --help` does not depend on install order.

Two test-collection fixes were needed to make the new tests actually run:
`testpaths` pointed at `packages/nooa-cli/tests/{cli,integration}`, neither of
which exists, so nothing under `packages/nooa-cli/tests` was ever collected in
CI. Replacing both with the parent directory exposed a latent collision — the
empty `packages/nooa-cli/tests/__init__.py` made it a package named `tests`,
shadowing the root `tests` package that other modules import from. It is
unnecessary under the repo's `--import-mode=importlib`, and
`packages/nooa-bench/tests` already ships without one.

Signed-off-by: Severin Klingler <sklingler@nvidia.com>

Author: sklinglernv

packages/nooa-cli/src/nooa_cli/AGENTS.md

@@ -101,6 +101,35 @@ def command(args: tuple[str, ...]):
     subprocess.run([sys.executable, "-m", "some_other_tool", *args])
 ```
 
+## Commands From Another Package
+
+If your command lives in a *different* installed package (not in this repo),
+register it in the `nooa_cli.commands` entry-point group instead of dropping a
+file here. The entry-point name becomes the subcommand name:
+
+```toml
+# pyproject.toml of your package
+[project.entry-points."nooa_cli.commands"]
+tui  = "my_package.cli.tui:command"
+term = "my_package.cli.term:command"
+```
+
+`my_package.cli.tui:command` must be a `click.Command` or `click.Group` — the
+same contract as an in-repo command module.
+
+- **Built-ins win name collisions.** A plugin can't shadow `eval`, `config`,
+  or anything else shipped here; it's logged and skipped.
+- **A broken plugin is skipped, not fatal.** An entry point that fails to
+  import, or that resolves to a non-`click.Command`, logs a warning and is
+  left out. `nooa` keeps working.
+- Plugins register in entry-point-name order, so `nooa --help` is stable
+  regardless of install order.
+- The **Performance Rule** below applies with extra force: every registered
+  entry point is loaded on *every* `nooa` invocation, including `nooa --help`.
+  Keep heavy imports inside the handler.
+
+This mirrors the existing `nooa.skills` and `nooa.bundled_configs` groups.
+
 ## Shared Utilities
 
 Common helpers live in `src/nooa_cli/_common.py`:

packages/nooa-cli/src/nooa_cli/__init__.py

@@ -9,7 +9,10 @@
     nooa completion install         # Set up shell completions
 
 Adding new commands:
-    Drop a .py file in nooa_cli/commands/ — see commands/_template.py
+    In this package: drop a .py file in nooa_cli/commands/ — see
+    commands/_template.py
+    From another package: register an entry point in the
+    "nooa_cli.commands" group — see nooa_cli/commands/__init__.py
 
 Shell completion:
     eval "$(_NOOA_COMPLETE=bash_source nooa)"    # bash
@@ -36,7 +39,8 @@ def oo(ctx):
     """OO Agents — agent toolkit.
 
     Extensible CLI for running agents, evaluations, and trace management.
-    Add new commands by dropping a .py file in nooa_cli/commands/.
+    Add new commands by dropping a .py file in nooa_cli/commands/, or from
+    another package via the "nooa_cli.commands" entry-point group.
     """
     if ctx.invoked_subcommand in _SKIP_SECRETS_PRELOAD:
         return
@@ -57,11 +61,14 @@ def oo(ctx):
         )
 
 
-# -- Auto-discover and register all commands from commands/ -----------------
+# -- Auto-discover and register all commands (built-ins + entry-point plugins) --
 for _name, _cmd in discover_commands():
     oo.add_command(_cmd, name=_name)
 
 # -- Built-in infrastructure commands (not in commands/ because they're meta) -
+# Registered *after* discovery on purpose: `completion` is not part of
+# discover_commands(), so this ordering is what stops a third-party plugin
+# named "completion" from taking the name.
 oo.add_command(completion)
 
 

packages/nooa-cli/src/nooa_cli/commands/__init__.py

@@ -13,6 +13,9 @@
 ║                                                                      ║
 ║  See _template.py for a copy-paste starter.                          ║
 ║                                                                      ║
+║  From *another* package? Register an entry point instead —           ║
+║  see "Commands from other packages" below.                           ║
+║                                                                      ║
 ╚══════════════════════════════════════════════════════════════════════╝
 
 Convention
@@ -62,22 +65,58 @@ def list():
     def create(name):
         \"\"\"Create a new thing.\"\"\"
         click.echo(f"Created {name}")
+
+Commands from other packages
+----------------------------
+
+A package installed alongside ``nooa-cli`` can contribute top-level
+subcommands through the ``nooa_cli.commands`` entry-point group. The
+entry-point name is the subcommand name; the object it points at must be a
+``click.Command``::
+
+    # pyproject.toml of the contributing package
+    [project.entry-points."nooa_cli.commands"]
+    tui  = "my_package.cli.tui:command"
+    term = "my_package.cli.term:command"
+
+Rules:
+
+* **Built-ins win name collisions.** A plugin cannot shadow ``eval``,
+  ``config`` or any other command shipped here — it is logged and skipped.
+* **Broken plugins are skipped, not fatal.** An entry point that fails to
+  import, or that resolves to something other than a ``click.Command``, logs a
+  warning and is left out; ``nooa`` keeps working.
+* Plugins are registered in entry-point-name order, so ``nooa --help`` is
+  stable regardless of install order.
+* **Keep imports lazy**, exactly as for in-repo commands: every registered
+  entry point is loaded on *every* ``nooa`` invocation, including
+  ``nooa --help``, so heavy imports belong inside the command handler.
 """
 
 import importlib
+import logging
 import pkgutil
 from collections.abc import Iterator
+from importlib import metadata
 
 import click
 
+logger = logging.getLogger(__name__)
+
+#: Entry-point group external packages use to contribute subcommands.
+PLUGIN_ENTRY_POINT_GROUP = "nooa_cli.commands"
 
-def discover_commands() -> Iterator[tuple[str, click.Command]]:
-    """Yield (name, command) pairs from all command modules in this package.
+
+def _builtin_commands() -> Iterator[tuple[str, click.Command]]:
+    """Yield (name, command) pairs from the command modules in this package.
 
     Scans this directory for Python modules, imports each one, and looks
     for a ``command`` attribute that is a ``click.Command`` or ``click.Group``.
 
     Modules starting with ``_`` are skipped (private / template files).
+
+    Unlike the plugin pass, a malformed module here raises: it is a bug in
+    this repository and should be loud.
     """
     package_path = __path__
     package_name = __name__
@@ -104,3 +143,66 @@ def discover_commands() -> Iterator[tuple[str, click.Command]]:
         name = getattr(module, "NAME", module_info.name)
 
         yield name, cmd
+
+
+def _plugin_commands() -> Iterator[tuple[str, click.Command]]:
+    """Yield (name, command) pairs contributed by other installed packages.
+
+    Reads the ``nooa_cli.commands`` entry-point group. The entry-point name
+    becomes the subcommand name, and ``ep.load()`` must return a
+    ``click.Command``.
+
+    Entry points are sorted by name so the command list does not depend on
+    install order. Every failure is logged at WARNING and skipped: these are
+    arbitrary third-party imports, and a broken one must never make ``nooa``
+    unusable.
+    """
+    try:
+        eps = metadata.entry_points(group=PLUGIN_ENTRY_POINT_GROUP)
+    except Exception:  # noqa: BLE001 — importlib.metadata can raise on broken installs
+        logger.warning(
+            "Failed to enumerate %r entry points", PLUGIN_ENTRY_POINT_GROUP, exc_info=True
+        )
+        return
+
+    for ep in sorted(eps, key=lambda e: e.name):
+        try:
+            cmd = ep.load()
+        except Exception:  # noqa: BLE001 — third-party entry-point code, be defensive
+            logger.warning("CLI plugin entry-point %r failed to load", ep.name, exc_info=True)
+            continue
+
+        if not isinstance(cmd, click.Command):
+            logger.warning(
+                "CLI plugin entry-point %r resolved to %s, not a click.Command; skipping",
+                ep.name,
+                type(cmd).__name__,
+            )
+            continue
+
+        yield ep.name, cmd
+
+
+def discover_commands() -> Iterator[tuple[str, click.Command]]:
+    """Yield (name, command) pairs for every subcommand of ``nooa``.
+
+    Built-in commands from this package come first, then commands contributed
+    by other packages through the ``nooa_cli.commands`` entry-point group.
+    A plugin whose name is already taken is logged and skipped, so built-ins
+    always win and each name is yielded exactly once.
+    """
+    seen: set[str] = set()
+
+    for name, cmd in _builtin_commands():
+        seen.add(name)
+        yield name, cmd
+
+    for name, cmd in _plugin_commands():
+        if name in seen:
+            logger.warning(
+                "CLI plugin entry-point %r shadows an existing command; ignoring the plugin",
+                name,
+            )
+            continue
+        seen.add(name)
+        yield name, cmd