feat(core): add shared structured logger with idempotent handler attach

Also adds root conftest.py so pytest caplog captures records from
non-propagating loggers (propagate=False is required by the logger spec).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

conftest.py

@@ -0,0 +1,37 @@
+"""Root conftest: ensure caplog captures from non-propagating loggers."""
+from __future__ import annotations
+
+import logging
+from contextlib import contextmanager
+from typing import Generator
+
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def _patch_caplog_for_no_propagate(caplog):
+    """Attach the caplog handler directly to every named logger that has
+    propagate=False so that ``caplog`` can still capture their records."""
+    _orig_at_level = caplog.at_level.__func__  # type: ignore[attr-defined]
+
+    @contextmanager
+    def patched_at_level(
+        self,
+        level: int,
+        logger: str | None = None,
+    ) -> Generator[None, None, None]:
+        logger_obj = logging.getLogger(logger) if logger else logging.getLogger()
+        added = False
+        if not logger_obj.propagate:
+            logger_obj.addHandler(self.handler)
+            added = True
+        try:
+            with _orig_at_level(self, level, logger):
+                yield
+        finally:
+            if added:
+                logger_obj.removeHandler(self.handler)
+
+    import types
+    caplog.at_level = types.MethodType(patched_at_level, caplog)
+    yield

src/core/logger.py

@@ -0,0 +1,38 @@
+"""Shared structured logger for NeuroBridge pipelines.
+
+All modules in `src/` must obtain their logger via `get_logger(__name__)`
+instead of using `print()`. This guarantees consistent format and INFO-level
+traceability across pipelines (per AGENTS.md §4).
+"""
+from __future__ import annotations
+
+import logging
+import sys
+
+_LOG_FORMAT = "%(asctime)s | %(levelname)-7s | %(name)s | %(message)s"
+_DATE_FORMAT = "%Y-%m-%dT%H:%M:%S"
+
+
+def get_logger(name: str, level: int = logging.INFO) -> logging.Logger:
+    """Return a process-wide singleton logger for the given name.
+
+    Idempotent: repeated calls with the same name return the same Logger
+    instance and never stack duplicate handlers.
+
+    Args:
+        name: Dotted logger name, conventionally `__name__`.
+        level: Logging level (default `logging.INFO`).
+
+    Returns:
+        Configured `logging.Logger` writing to stdout.
+    """
+    logger = logging.getLogger(name)
+    if logger.handlers:
+        return logger
+
+    handler = logging.StreamHandler(stream=sys.stdout)
+    handler.setFormatter(logging.Formatter(_LOG_FORMAT, datefmt=_DATE_FORMAT))
+    logger.addHandler(handler)
+    logger.setLevel(level)
+    logger.propagate = False
+    return logger

tests/core/test_logger.py

@@ -0,0 +1,33 @@
+"""Unit tests for the shared structured logger."""
+from __future__ import annotations
+
+import logging
+
+from src.core.logger import get_logger
+
+
+def test_get_logger_returns_logger_instance() -> None:
+    logger = get_logger("neurobridge.test")
+    assert isinstance(logger, logging.Logger)
+    assert logger.name == "neurobridge.test"
+
+
+def test_get_logger_attaches_single_handler() -> None:
+    """Repeated calls must not duplicate handlers (idempotence)."""
+    name = "neurobridge.idempotent"
+    first = get_logger(name)
+    second = get_logger(name)
+    assert first is second
+    assert len(first.handlers) == 1
+
+
+def test_get_logger_default_level_is_info() -> None:
+    logger = get_logger("neurobridge.level_check")
+    assert logger.level == logging.INFO
+
+
+def test_get_logger_emits_formatted_record(caplog) -> None:
+    logger = get_logger("neurobridge.emit")
+    with caplog.at_level(logging.INFO, logger="neurobridge.emit"):
+        logger.info("hello-world")
+    assert any("hello-world" in record.message for record in caplog.records)