feat(disk): add dir_exists() as the directory-only sibling of file_exists()

`file_exists()` wraps `os.path.isfile()` and therefore returns False for
directories, which is easy to miss when reading a caller. The new
`dir_exists()` makes the intent explicit and avoids the trap of
silently never matching directory paths. The docstring on `file_exists`
now also calls out the file-only behavior and points readers at
`dir_exists`.

Author: markuslf

CHANGELOG.md

@@ -8,7 +8,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-tbd
+### Added
+
+* disk.py: add `dir_exists()` as the directory-only counterpart to `file_exists()`. The existing `file_exists()` wraps `os.path.isfile()` and therefore returns `False` for directories, which is easy to miss; callers that want to check for a directory should now use `dir_exists()`
 
 
 ## [v3.0.0] - 2026-04-13

disk.py

@@ -55,9 +55,42 @@ def bd2dmd(device):
     return mapped_device if os.path.islink(mapped_device) else ''
 
 
+def dir_exists(path):
+    """
+    Check if a directory exists at the given path.
+
+    Use this when you specifically want a directory check. `file_exists()`
+    only returns `True` for regular files (it is `os.path.isfile()` under
+    the hood), so passing a directory to it always returns `False`.
+
+    ### Parameters
+    - **path** (`str`):
+      The path to the directory to check.
+
+    ### Returns
+    - **bool**:
+      `True` if the path exists and is a directory (or a symlink to one),
+      `False` otherwise.
+
+    ### Example
+    >>> dir_exists('/etc')
+    True
+    >>> dir_exists('/etc/passwd')
+    False
+    >>> dir_exists('/path/that/does/not/exist')
+    False
+    """
+    return os.path.isdir(path)
+
+
 def file_exists(path, allow_empty=False):
     """
-    Check if a file exists at the given path, optionally allowing empty files.
+    Check if a regular file exists at the given path, optionally allowing
+    empty files.
+
+    This wraps `os.path.isfile()`, so it only matches regular files and
+    symlinks pointing at regular files. Directories return `False`; use
+    `dir_exists()` for directory checks.
 
     ### Parameters
     - **path** (`str`):