π« Toolkit to help you get started with SDD or any other process!
chore: refactor event domain layout (#4683)
Manfred Riem6a8870ffcb14
diff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.pyindex ccc2be67f..126713538 100644--- a/src/specify_cli/__init__.py+++ b/src/specify_cli/__init__.py@@ -539,7 +539,7 @@ _register_integration_cmds(app)# ===== Event Commands =====-from .commands.event import register as _register_event_cmds # noqa: E402+from .events import register as _register_event_cmds # noqa: E402_register_event_cmds(app)# Re-export selected helpers to preserve the public import surface.diff --git a/src/specify_cli/events.py b/src/specify_cli/events/__init__.pysimilarity index 98%rename from src/specify_cli/events.pyrename to src/specify_cli/events/__init__.pyindex 363266171..b78e5da84 100644--- a/src/specify_cli/events.py+++ b/src/specify_cli/events/__init__.py@@ -1,9 +1,15 @@-"""Agent runtime events for integrations.+"""Agent runtime events and the ``specify event`` command group.Provides:- ``resolve_events`` β layered event resolution (CLI flag β YAML override β extension-declared β built-in).- ``collect_extension_events`` β scan installed extension.yml files for ``events:``.- ``install_integration_events`` / ``remove_integration_events`` β entry points called from ``IntegrationBase.setup()`` / ``teardown()``.++The singular CLI namespace intentionally maps to the plural Python package.+``specify_cli.events`` is an established domain API and monkeypatch boundary,+so preserving it takes precedence over matching the CLI spelling on disk.+``command_run`` contains the nested CLI adapter; this module owns the domain+API, Typer application, and registration."""from __future__ import annotations@@ -21,13 +27,20 @@ from pathlib import Path, PurePosixPath, PureWindowsPathfrom typing import TYPE_CHECKING, Anyimport yaml+import typerif TYPE_CHECKING:- from .integrations.base import IntegrationBase- from .integrations.manifest import IntegrationManifest+ from ..integrations.base import IntegrationBase+ from ..integrations.manifest import IntegrationManifestlogger = logging.getLogger(__name__)+event_app = typer.Typer(+ name="event",+ help="Manage and execute event-driven commands",+ add_completion=False,+)+# -- Constants -------------------------------------------------------------# Generated hook dispatchers refuse to delegate unless this name is True.@@ -526,7 +539,7 @@ def _find_command_template(command_name: str, project_root: Path) -> tuple[Path# on-disk fallback below.disabled_ids = _disabled_extension_ids(project_root)try:- from .extensions import ExtensionManager+ from ..extensions import ExtensionManagermanager = ExtensionManager(project_root)for ext_id in sorted(manager.registry.keys()):if ext_id in disabled_ids:@@ -572,7 +585,7 @@ def _find_command_template(command_name: str, project_root: Path) -> tuple[Path# templates/commands). The previous bespoke inspect.getfile() math# pointed at core_pack/templates/commands, which never exists in a# wheel build (force-include maps templates/commands -> core_pack/commands).- from ._assets import _locate_core_pack, _repo_root+ from .._assets import _locate_core_pack, _repo_rootcore_pack = _locate_core_pack()candidate_dirs = [core_pack / "commands" if core_pack is not None else None,@@ -626,7 +639,7 @@ def _resolve_event_command_argv(``.py``, the platform shell otherwise). Returns ``None`` if no runnablescript is declared."""- from .integrations.base import IntegrationBase+ from ..integrations.base import IntegrationBasetry:content = template_path.read_text(encoding="utf-8")@@ -730,7 +743,7 @@ def _load_project_script_type(project_root: Path) -> str:"""default = "ps" if platform.system().lower().startswith("win") else "sh"try:- from ._init_options import load_init_options+ from .._init_options import load_init_optionsopts = load_init_options(project_root)if isinstance(opts, dict):script = opts.get("script")@@ -885,7 +898,7 @@ def _validate_resolved_event(event_name: str, handlers: list[dict[str, Any]]) ->#17). Malformed-but-skipable entries are already dropped by``_normalize_handlers``."""- from .extensions import ValidationError+ from ..extensions import ValidationErrorif event_name not in CANONICAL_EVENTS:raise ValidationError(@@ -1039,7 +1052,7 @@ def _disabled_extension_ids(project_root: Path) -> set[str]:disabled extension after its config file was preserved (e.g. a JSONCparse failure that skipped native cleanup)."""- from .extensions import ExtensionRegistry+ from ..extensions import ExtensionRegistryexts_dir = project_root / ".specify" / "extensions"disabled_ids: set[str] = set()@@ -1075,7 +1088,7 @@ def collect_extension_events(project_root: Path) -> ResolvedEvents:obsolete name and ``_find_command_template`` could not match it, leavingthe hook silently inert."""- from .extensions import ExtensionManager+ from ..extensions import ExtensionManagerevents: ResolvedEvents = {}exts_dir = project_root / ".specify" / "extensions"@@ -1143,7 +1156,7 @@ def _resolve_interpreter(project_root: Path) -> str:commands honor the project venv and never hard-code ``python3`` (which iscommonly absent on Windows even when ``py.exe``/``python.exe`` exist)."""- from .integrations.base import IntegrationBase+ from ..integrations.base import IntegrationBasereturn IntegrationBase.resolve_python_interpreter(project_root)@@ -1686,9 +1699,9 @@ def _other_event_integrations_reference_dispatcher(for the dispatcher path so uninstalling one multi-install event-capableintegration doesn't delete the dispatcher the others still rely on."""- from .integrations._helpers import _read_integration_json- from .integrations.manifest import IntegrationManifest- from .integration_state import installed_integration_keys+ from ..integrations._helpers import _read_integration_json+ from ..integrations.manifest import IntegrationManifest+ from ..integration_state import installed_integration_keysstate = _read_integration_json(project_root)for key in installed_integration_keys(state):@@ -1763,7 +1776,7 @@ def remove_integration_events(def events_stale_exclusions(integration_key: str) -> set[str]:"""Return project-relative paths to protect from stale cleanup."""- from .integrations import get_integration+ from ..integrations import get_integrationintegration = get_integration(integration_key)if not integration:return set()@@ -1813,10 +1826,10 @@ def refresh_integration_events(project_root: Path) -> None:the lifecycle command can't claim the extension was fully deactivatedwhile a stale native hook may still be active (R3)."""- from .integrations import get_integration- from .integrations._helpers import _read_integration_json, _resolve_integration_options- from .integrations.manifest import IntegrationManifest- from .integration_state import installed_integration_keys+ from ..integrations import get_integration+ from ..integrations._helpers import _read_integration_json, _resolve_integration_options+ from ..integrations.manifest import IntegrationManifest+ from ..integration_state import installed_integration_keysstate = _read_integration_json(project_root)failures: list[tuple[str, str]] = []@@ -1863,7 +1876,7 @@ def refresh_integration_events(project_root: Path) -> None:def validate_events(data: dict[str, Any]) -> None:"""Validate ``events`` field in extension manifest data."""- from .extensions import ValidationError+ from ..extensions import ValidationErrorevents = data.get("events")if "events" in data and not isinstance(events, dict):@@ -1911,7 +1924,7 @@ def has_events(data: dict[str, Any]) -> bool:def _toml_quote(value: str) -> str:"""Render *value* as a TOML basic string via the shared escaper."""- from ._toml_string import escape_toml_basic+ from .._toml_string import escape_toml_basicreturn escape_toml_basic(value)@@ -2547,7 +2560,7 @@ def _ensure_safe_destination(dst: Path) -> None:outside the repo would redirect writes to external files). Then validateslexical containment so ``..`` traversal is also rejected."""- from .agents import CommandRegistrar+ from ..agents import CommandRegistrar# Walk each component so a symlinked ancestor (e.g. ``.claude`` β outside)# cannot be silently followed. Mirrors IntegrationManifest.record_existing.@@ -2619,3 +2632,10 @@ def _has_marker(entry: Any) -> bool:if isinstance(inner, list):return any(_has_marker(h) for h in inner)return False+++def register(app: typer.Typer) -> None:+ """Attach the event command group to the root application."""+ from . import command_run # noqa: F401 -- registers handler++ app.add_typer(event_app, name="event")diff --git a/src/specify_cli/commands/event.py b/src/specify_cli/events/command_run.pysimilarity index 86%rename from src/specify_cli/commands/event.pyrename to src/specify_cli/events/command_run.pyindex 47bcf86e7..c5bf162b3 100644--- a/src/specify_cli/commands/event.py+++ b/src/specify_cli/events/command_run.py@@ -1,16 +1,13 @@-"""specify event * command handlers."""+"""CLI adapter for ``specify event run``."""from __future__ import annotationsfrom pathlib import Pathimport sys+import typer-event_app = typer.Typer(- name="event",- help="Manage and execute event-driven commands",- add_completion=False,-)+from . import event_app@event_app.command("run")@@ -22,7 +19,7 @@ def event_run(),):"""Resolve and run an event-driven command script with stdin payload."""- from ..events import resolve_and_run_event_command+ from . import resolve_and_run_event_command# Read payload from stdin if available (capped at 1 MiB to prevent DoS).MAX_STDIN_BYTES = 1 * 1024 * 1024@@ -55,7 +52,3 @@ def event_run(command_name, event_name, payload, project_root, timeout=timeout)raise typer.Exit(code=exit_code)---def register(app: typer.Typer) -> None:- app.add_typer(event_app, name="event")diff --git a/tests/specify_cli/events/__init__.py b/tests/specify_cli/events/__init__.pynew file mode 100644index 000000000..52c5b633f--- /dev/null+++ b/tests/specify_cli/events/__init__.py@@ -0,0 +1 @@+"""Tests for the event domain and its nested command surface."""diff --git a/tests/test_event_command.py b/tests/specify_cli/events/test_command_run.pysimilarity index 95%rename from tests/test_event_command.pyrename to tests/specify_cli/events/test_command_run.pyindex 0a431fb5c..6782b1dd2 100644--- a/tests/test_event_command.py+++ b/tests/specify_cli/events/test_command_run.py@@ -1,6 +1,6 @@"""`specify event run` must read piped stdin without crashing.-`event_run` (src/specify_cli/commands/event.py) capped its stdin read at 1+`event_run` (src/specify_cli/events/command_run.py) capped its stdin read at 1MiB to prevent a DoS (#3857), but the truncation check read a `.eof`attribute that does not exist on any Python file-like object (including`sys.stdin`) β every piped-stdin invocation raised `AttributeError` instead@@ -22,7 +22,7 @@ import typerfrom typer.testing import CliRunnerfrom specify_cli import app-from specify_cli.commands.event import event_run+from specify_cli.events.command_run import event_rundef test_event_run_reads_piped_stdin_payload():@@ -71,7 +71,7 @@ def test_event_run_tty_uses_empty_object(monkeypatch):def isatty(self):return True- monkeypatch.setattr("specify_cli.commands.event.sys.stdin", FakeTtyStdin())+ monkeypatch.setattr("specify_cli.events.command_run.sys.stdin", FakeTtyStdin())with patch("specify_cli.events.resolve_and_run_event_command", return_value=0diff --git a/tests/integrations/test_events.py b/tests/specify_cli/events/test_events.pysimilarity index 99%rename from tests/integrations/test_events.pyrename to tests/specify_cli/events/test_events.pyindex 946acc3c2..9a193c762 100644--- a/tests/integrations/test_events.py+++ b/tests/specify_cli/events/test_events.py@@ -1,4 +1,4 @@-"""Tests for events module: integration runtime events."""+"""Tests for the event domain and integration runtime hooks."""from __future__ import annotations