oaknut-extension 12.0.0__tar.gz

oaknut_extension-12.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robert Smallshire
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

oaknut_extension-12.0.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: oaknut-extension
+Version: 12.0.0
+Summary: Entry-point plug-in framework shared by every extensible axis of the oaknut package family.
+Author-email: Robert Smallshire <robert@smallshire.org.uk>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rob-smallshire/oaknut/tree/master/packages/oaknut-extension
+Project-URL: Repository, https://github.com/rob-smallshire/oaknut
+Project-URL: Issues, https://github.com/rob-smallshire/oaknut/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: oaknut-exception>=10.0
+Requires-Dist: stevedore>=5.0
+Dynamic: license-file
+
+# oaknut-extension
+
+The entry-point plug-in framework shared by every extensible *axis* of the
+`oaknut` package family.
+
+An **axis** is one extension point — a family of interchangeable plug-ins that
+all answer the same question. The primary axis is *filesystems* (each plug-in
+detects and operates on one disc format, in `oaknut-filesystem`);
+`oaknut.command` (CLI subcommands contributed by filesystem packages) is
+another.
+
+Each axis declares a `kind` (a short identifier such as `"filesystem"`).
+Concrete extensions for that axis subclass `Extension`, override `_kind()`,
+and register themselves under the `oaknut.<kind>` entry-point namespace in
+their package's `pyproject.toml`:
+
+```toml
+[project.entry-points."oaknut.filesystem"]
+acorn-dfs = "oaknut.dfs.filesystem:AcornDFS"
+```
+
+Consumers discover and load them through `list_extensions()`,
+`create_extension()`, and friends, which wrap [stevedore](https://docs.openstack.org/stevedore/).
+Because discovery is by installed entry point, a plug-in shipped by any package
+appears automatically — no central registry to edit.
+
+This package is deliberately domain-agnostic: it knows nothing about discs,
+files, or formats. It depends only on `oaknut-exception` (for the shared error
+hierarchy) and `stevedore`.

oaknut_extension-12.0.0/README.md

@@ -0,0 +1,29 @@
+# oaknut-extension
+
+The entry-point plug-in framework shared by every extensible *axis* of the
+`oaknut` package family.
+
+An **axis** is one extension point — a family of interchangeable plug-ins that
+all answer the same question. The primary axis is *filesystems* (each plug-in
+detects and operates on one disc format, in `oaknut-filesystem`);
+`oaknut.command` (CLI subcommands contributed by filesystem packages) is
+another.
+
+Each axis declares a `kind` (a short identifier such as `"filesystem"`).
+Concrete extensions for that axis subclass `Extension`, override `_kind()`,
+and register themselves under the `oaknut.<kind>` entry-point namespace in
+their package's `pyproject.toml`:
+
+```toml
+[project.entry-points."oaknut.filesystem"]
+acorn-dfs = "oaknut.dfs.filesystem:AcornDFS"
+```
+
+Consumers discover and load them through `list_extensions()`,
+`create_extension()`, and friends, which wrap [stevedore](https://docs.openstack.org/stevedore/).
+Because discovery is by installed entry point, a plug-in shipped by any package
+appears automatically — no central registry to edit.
+
+This package is deliberately domain-agnostic: it knows nothing about discs,
+files, or formats. It depends only on `oaknut-exception` (for the shared error
+hierarchy) and `stevedore`.

oaknut_extension-12.0.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "oaknut-extension"
+dynamic = ["version"]
+authors = [{ name = "Robert Smallshire", email = "robert@smallshire.org.uk" }]
+description = "Entry-point plug-in framework shared by every extensible axis of the oaknut package family."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "oaknut-exception>=10.0",
+    "stevedore>=5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/rob-smallshire/oaknut/tree/master/packages/oaknut-extension"
+Repository = "https://github.com/rob-smallshire/oaknut"
+Issues = "https://github.com/rob-smallshire/oaknut/issues"
+
+[dependency-groups]
+test = [
+    "pytest>=8.0",
+]
+dev = [
+    "bump-my-version>=0.28.0",
+    "pre-commit>=3.0",
+    {include-group = "test"},
+]
+
+[tool.setuptools.dynamic]
+version = { attr = "oaknut.extension.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

oaknut_extension-12.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

oaknut_extension-12.0.0/src/oaknut/extension/__init__.py

@@ -0,0 +1,293 @@
+"""Generic entry-point plug-in machinery shared by every oaknut extension axis.
+
+An *axis* is a single extension point — a family of interchangeable
+plug-ins that all answer the same question (for example the *filesystem*
+axis, where each plug-in detects and operates on one disc format). Each
+axis declares a ``kind`` (a short identifier such as ``"filesystem"``).
+Concrete extensions subclass :class:`Extension`, override
+:meth:`Extension._kind`, and are registered under the ``oaknut.<kind>``
+entry-point namespace in their package's ``pyproject.toml``::
+
+    [project.entry-points."oaknut.filesystem"]
+    acorn-dfs = "oaknut.dfs.filesystem:AcornDFS"
+
+Consumers discover and load them via :func:`list_extensions`,
+:func:`create_extension`, :func:`extension`, and :func:`describe_extension`,
+which wrap `stevedore <https://docs.openstack.org/stevedore/>`_. Because
+discovery is by installed entry point, a plug-in shipped by any package
+appears automatically — there is no central registry to edit.
+
+This module is the clone-and-own foundation for the family: it is
+deliberately domain-agnostic, knowing nothing about discs, files, or
+formats. Per-axis packages build a thin convenience layer on top (see
+``oaknut.filesystem`` for the filesystem axis).
+"""
+
+from __future__ import annotations
+
+import functools
+import importlib.resources
+import inspect
+import logging
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Optional, Type
+
+import stevedore
+import stevedore.driver
+import stevedore.exception
+import stevedore.extension
+from oaknut.exception import ConfigurationError
+from oaknut.extension._text import first_line, normalize_name, strip_lines
+
+__version__ = "12.0.0"
+
+#: Entry-point namespaces are formed as ``"<NAMESPACE_PREFIX>.<kind>"``.
+NAMESPACE_PREFIX = "oaknut"
+
+__all__ = [
+    "Extension",
+    "ExtensionError",
+    "namespace_for",
+    "create_extension",
+    "extension",
+    "describe_extension",
+    "list_extensions",
+    "list_dirpaths",
+    "extension_name_from_class",
+    "load_failure_callback",
+]
+
+logger = logging.getLogger(__name__)
+
+
+def namespace_for(kind: str) -> str:
+    """Return the entry-point namespace for an extension *kind*.
+
+    The convention is ``"oaknut.<kind>"`` — e.g.
+    ``namespace_for("filesystem")`` is ``"oaknut.filesystem"``.
+    """
+    return f"{NAMESPACE_PREFIX}.{kind}"
+
+
+class Extension(ABC):
+    """Base class for every oaknut plug-in extension.
+
+    A concrete extension overrides :meth:`_kind` to name its axis and
+    is instantiated with the entry-point ``name`` it was registered
+    under. The class docstring doubles as its human-readable
+    description (see :meth:`describe`).
+    """
+
+    def __init__(self, name: str, **kwargs):
+        super().__init__(**kwargs)
+        self._name = name
+
+    @classmethod
+    def kind(cls) -> str:
+        """The kind of extension — the axis this plug-in belongs to."""
+        return cls._kind()
+
+    @classmethod
+    @abstractmethod
+    def _kind(cls) -> str:
+        raise NotImplementedError
+
+    @property
+    def name(self) -> str:
+        """The entry-point name this extension was loaded under."""
+        return self._name
+
+    @classmethod
+    def dirpath(cls) -> Path:
+        """The directory path to the package providing this extension."""
+        package_name = inspect.getmodule(cls).__package__
+        return Path(importlib.resources.files(package_name))
+
+    @classmethod
+    def version(cls) -> str:
+        """The extension version. Override to report something meaningful."""
+        return __version__
+
+    @classmethod
+    def describe(cls, *, single_line: bool = False) -> str:
+        """A human-readable description of the extension.
+
+        By default this is the extension class's docstring. Override it
+        if you want something different.
+
+        Args:
+            single_line: If True, return only the first non-empty line of
+                the description. Defaults to False for the full text.
+
+        Returns:
+            The description. If *single_line* is True, only the first
+            non-empty line; otherwise the complete (de-indented) docstring.
+        """
+        if cls.__doc__ is None:
+            return "No description available."
+        full_description = strip_lines(inspect.cleandoc(cls.__doc__))
+        if single_line:
+            return first_line(full_description)
+        return full_description
+
+    @classmethod
+    @functools.lru_cache(maxsize=None)
+    def entry_point_name(cls) -> str:
+        """The entry-point name (key) this extension class is registered under.
+
+        Performs a reverse lookup from class to entry-point name by
+        searching the axis's namespace. Cached indefinitely since
+        entry-point names are immutable for the life of the process.
+
+        Raises:
+            ExtensionError: If this class is not a registered extension.
+        """
+        return extension_name_from_class(namespace_for(cls.kind()), cls)
+
+
+class ExtensionError(ConfigurationError):
+    """Raised when an extension cannot be discovered or loaded.
+
+    A plug-in that is missing, mis-registered, or fails at import time
+    is an environment/setup problem rather than bad input or a library
+    bug — hence a :class:`~oaknut.exception.ConfigurationError`.
+    """
+
+
+def create_extension(
+    kind: str,
+    namespace: str,
+    name: str,
+    exception_type: Optional[type[BaseException]] = None,
+    **kwargs,
+) -> Extension:
+    """Instantiate an extension by name.
+
+    Args:
+        kind: The kind of extension (for error messages).
+        namespace: The entry-point namespace to search.
+        name: The name of the extension to load.
+        exception_type: Exception raised if the extension cannot be
+            loaded. Defaults to :class:`ExtensionError`.
+        **kwargs: Forwarded to the extension constructor.
+
+    Returns:
+        An :class:`Extension` instance.
+    """
+    ext = extension(kind, namespace, name, exception_type)
+    return ext(name=normalize_name(name), **kwargs)
+
+
+def extension(
+    kind: str,
+    namespace: str,
+    name: str,
+    exception_type: Optional[type[BaseException]] = None,
+) -> Type[Extension]:
+    """Get an extension *class* (without instantiating it).
+
+    Args:
+        kind: The kind of extension (for error messages).
+        namespace: The entry-point namespace to search.
+        name: The name of the extension to load.
+        exception_type: Exception raised if the extension cannot be
+            loaded. Defaults to :class:`ExtensionError`.
+
+    Returns:
+        The extension class.
+    """
+    exception_type = exception_type or ExtensionError
+    normal_name = normalize_name(name)
+    try:
+        manager = stevedore.driver.DriverManager(
+            namespace=namespace,
+            name=normal_name,
+            invoke_on_load=False,
+            on_load_failure_callback=load_failure_callback,
+        )
+    except stevedore.exception.NoMatches as no_matches:
+        name_list = ", ".join(list_extensions(namespace))
+        raise exception_type(
+            f"No {kind} matching {name!r}. Available {kind}s: {name_list}"
+        ) from no_matches
+    return manager.driver
+
+
+def describe_extension(
+    kind: str,
+    namespace: str,
+    name: str,
+    exception_type: Optional[type[BaseException]] = None,
+    *,
+    single_line: bool = False,
+) -> str:
+    """Return the description of an extension by name.
+
+    Args:
+        kind: The kind of extension (for error messages).
+        namespace: The entry-point namespace to search.
+        name: The name of the extension.
+        exception_type: Exception raised if the extension cannot be loaded.
+        single_line: If True, return only the first non-empty line.
+
+    Returns:
+        The extension's description string.
+    """
+    driver = extension(kind, namespace, name, exception_type)
+    return driver.describe(single_line=single_line)
+
+
+def list_extensions(namespace: str) -> list[str]:
+    """List the names of the extensions registered in *namespace*."""
+    manager = stevedore.ExtensionManager(
+        namespace=namespace,
+        invoke_on_load=False,
+        on_load_failure_callback=load_failure_callback,
+    )
+    return manager.names()
+
+
+def list_dirpaths(namespace: str) -> dict[str, Path]:
+    """Map each extension name in *namespace* to its package directory path."""
+    manager = stevedore.ExtensionManager(
+        namespace=namespace,
+        invoke_on_load=False,
+        on_load_failure_callback=load_failure_callback,
+    )
+    return {name: _extension_dirpath(ext) for name, ext in manager.items()}
+
+
+def _extension_dirpath(ext: stevedore.extension.Extension) -> Path:
+    """The directory path to the package providing a stevedore extension."""
+    return Path(importlib.resources.files(ext.module_name))
+
+
+def extension_name_from_class(namespace: str, extension_class: Type[Extension]) -> str:
+    """Reverse-lookup the entry-point name for an extension *class*.
+
+    Iterates the extensions in *namespace* until one whose plug-in is
+    *extension_class* is found.
+
+    Raises:
+        ExtensionError: If the class is not registered in *namespace*.
+    """
+    manager = stevedore.ExtensionManager(
+        namespace=namespace,
+        invoke_on_load=False,
+        on_load_failure_callback=load_failure_callback,
+    )
+    for ext in manager:
+        if ext.plugin is extension_class:
+            return ext.name
+    raise ExtensionError(
+        f"Extension class {extension_class.__name__} not found in namespace {namespace!r}"
+    )
+
+
+def load_failure_callback(manager, entrypoint, exception):
+    """Turn a stevedore load failure into an :class:`ExtensionError`."""
+    raise ExtensionError(
+        f"Could not load extension {entrypoint.name!r} from namespace "
+        f"{manager.namespace!r}: {exception}"
+    ) from exception

oaknut_extension-12.0.0/src/oaknut/extension/_text.py

@@ -0,0 +1,58 @@
+"""Internal text utilities for rendering extension descriptions.
+
+These small helpers are used by :mod:`oaknut.extension` to turn an
+extension class's docstring into a one-line summary or a tidied block.
+They are kept internal (underscore-prefixed module) because they are
+not part of the public API.
+"""
+
+
+def _is_blank(line: str) -> bool:
+    return not line or line.isspace()
+
+
+def strip_lines(text: str) -> str:
+    """Remove leading and trailing blank lines.
+
+    Args:
+        text: The text to process.
+
+    Returns:
+        The text with any leading and trailing blank-or-whitespace-only
+        lines removed. Interior blank lines are preserved.
+    """
+    lines = text.splitlines()
+    start = 0
+    while start < len(lines) and _is_blank(lines[start]):
+        start += 1
+    end = len(lines)
+    while end > start and _is_blank(lines[end - 1]):
+        end -= 1
+    return "\n".join(lines[start:end])
+
+
+def normalize_name(name: str) -> str:
+    """Normalise an extension lookup name.
+
+    Trims surrounding whitespace only; the name is otherwise matched
+    against the registered entry-point key verbatim. Hyphens are
+    significant — oaknut's user-facing keys are hyphenated
+    (``acorn-dfs``) — so they are preserved, not folded to underscores.
+    """
+    return name.strip()
+
+
+def first_line(text: str) -> str:
+    """Extract the first non-empty line from *text*.
+
+    Useful for one-line summaries in tables where multi-line text wraps
+    awkwardly. Returns the empty string if *text* is empty or all
+    whitespace.
+    """
+    if not text:
+        return ""
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped:
+            return stripped
+    return ""

oaknut_extension-12.0.0/src/oaknut_extension.egg-info/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: oaknut-extension
+Version: 12.0.0
+Summary: Entry-point plug-in framework shared by every extensible axis of the oaknut package family.
+Author-email: Robert Smallshire <robert@smallshire.org.uk>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rob-smallshire/oaknut/tree/master/packages/oaknut-extension
+Project-URL: Repository, https://github.com/rob-smallshire/oaknut
+Project-URL: Issues, https://github.com/rob-smallshire/oaknut/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: oaknut-exception>=10.0
+Requires-Dist: stevedore>=5.0
+Dynamic: license-file
+
+# oaknut-extension
+
+The entry-point plug-in framework shared by every extensible *axis* of the
+`oaknut` package family.
+
+An **axis** is one extension point — a family of interchangeable plug-ins that
+all answer the same question. The primary axis is *filesystems* (each plug-in
+detects and operates on one disc format, in `oaknut-filesystem`);
+`oaknut.command` (CLI subcommands contributed by filesystem packages) is
+another.
+
+Each axis declares a `kind` (a short identifier such as `"filesystem"`).
+Concrete extensions for that axis subclass `Extension`, override `_kind()`,
+and register themselves under the `oaknut.<kind>` entry-point namespace in
+their package's `pyproject.toml`:
+
+```toml
+[project.entry-points."oaknut.filesystem"]
+acorn-dfs = "oaknut.dfs.filesystem:AcornDFS"
+```
+
+Consumers discover and load them through `list_extensions()`,
+`create_extension()`, and friends, which wrap [stevedore](https://docs.openstack.org/stevedore/).
+Because discovery is by installed entry point, a plug-in shipped by any package
+appears automatically — no central registry to edit.
+
+This package is deliberately domain-agnostic: it knows nothing about discs,
+files, or formats. It depends only on `oaknut-exception` (for the shared error
+hierarchy) and `stevedore`.

oaknut_extension-12.0.0/src/oaknut_extension.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/oaknut/extension/__init__.py
+src/oaknut/extension/_text.py
+src/oaknut_extension.egg-info/PKG-INFO
+src/oaknut_extension.egg-info/SOURCES.txt
+src/oaknut_extension.egg-info/dependency_links.txt
+src/oaknut_extension.egg-info/requires.txt
+src/oaknut_extension.egg-info/top_level.txt
+tests/test_extension.py

oaknut_extension-12.0.0/src/oaknut_extension.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

oaknut_extension-12.0.0/src/oaknut_extension.egg-info/requires.txt

@@ -0,0 +1,2 @@
+oaknut-exception>=10.0
+stevedore>=5.0

oaknut_extension-12.0.0/src/oaknut_extension.egg-info/top_level.txt

@@ -0,0 +1 @@
+oaknut

oaknut_extension-12.0.0/tests/test_extension.py

@@ -0,0 +1,97 @@
+"""Unit tests for the generic extension framework.
+
+End-to-end entry-point *discovery* is exercised where real plug-ins
+are registered (see the filesystem tests in oaknut-dfs / oaknut-adfs).
+Here we cover the axis-agnostic behaviour: the Extension contract,
+namespace formation, docstring-driven descriptions, and the
+not-found error path.
+"""
+
+import pytest
+from oaknut.exception import ConfigurationError, OaknutException
+from oaknut.extension import (
+    Extension,
+    ExtensionError,
+    extension,
+    namespace_for,
+)
+from oaknut.extension._text import first_line, normalize_name, strip_lines
+
+
+class _Widget(Extension):
+    """A test widget extension.
+
+    Second paragraph that should not appear in the single-line summary.
+    """
+
+    @classmethod
+    def _kind(cls):
+        return "widget"
+
+
+class _Undocumented(Extension):  # noqa: D101 — intentionally has no docstring
+    @classmethod
+    def _kind(cls):
+        return "widget"
+
+
+class TestNamespace:
+    def test_namespace_uses_oaknut_prefix(self):
+        assert namespace_for("filesystem") == "oaknut.filesystem"
+
+    def test_namespace_for_arbitrary_kind(self):
+        assert namespace_for("widget") == "oaknut.widget"
+
+
+class TestExtensionContract:
+    def test_kind_delegates_to_underscore_kind(self):
+        assert _Widget.kind() == "widget"
+
+    def test_name_is_the_constructor_argument(self):
+        assert _Widget(name="acme").name == "acme"
+
+    def test_version_defaults_to_package_version(self):
+        # Unified workspace versioning — a dotted release string.
+        assert _Widget.version().count(".") == 2
+
+
+class TestDescribe:
+    def test_describe_returns_full_docstring(self):
+        description = _Widget.describe()
+        assert "A test widget extension." in description
+        assert "Second paragraph" in description
+
+    def test_describe_single_line_is_first_line_only(self):
+        assert _Widget.describe(single_line=True) == "A test widget extension."
+
+    def test_describe_handles_missing_docstring(self):
+        assert _Undocumented.describe() == "No description available."
+
+
+class TestNotFound:
+    def test_unknown_extension_raises_extension_error(self):
+        with pytest.raises(ExtensionError) as exc_info:
+            extension("widget", "oaknut.widget", "does-not-exist")
+        # The message names what was sought so the user can self-correct.
+        assert "does-not-exist" in str(exc_info.value)
+
+    def test_extension_error_is_a_configuration_error(self):
+        # A mis-installed plug-in is a setup problem, not bad data —
+        # so it carries the configuration exit code, not a traceback.
+        assert issubclass(ExtensionError, ConfigurationError)
+        assert issubclass(ExtensionError, OaknutException)
+
+
+class TestTextHelpers:
+    def test_strip_lines_trims_blank_edges_but_keeps_interior(self):
+        assert strip_lines("\n\n a \n\n b \n\n") == " a \n\n b "
+
+    def test_first_line_skips_leading_blanks(self):
+        assert first_line("\n\n  hello  \nworld") == "hello"
+
+    def test_first_line_of_empty_is_empty(self):
+        assert first_line("   ") == ""
+
+    def test_normalize_name_preserves_hyphens(self):
+        # Keys are hyphenated and matched verbatim (only whitespace trimmed).
+        assert normalize_name("  acorn-dfs  ") == "acorn-dfs"