refactor(tools): modernise basket-* helpers around a shared _basket module

Bring basket-compare, basket-join and basket-remove-uuids onto
the same shape as the rest of the tools/ tree, and introduce
`tools/_basket.py` for the load / save / duplicate-key plumbing
that each of the three previously rolled on its own.

_common.py:
- Add `dummy` to SKIP_PLUGINS. The `check-plugins/dummy` plugin
  is the minimal argparse-plus-output skeleton and should never
  have been picked up by tools that walk check-plugins/.
- Generalise `iter_check_plugins()` into `iter_plugin_dirs(subdir)`
  so tools that also walk notification-plugins/ can reuse the
  same sorted, SKIP_PLUGINS-aware iterator.

_basket.py (new):
- DuplicateKeyError + _raise_on_duplicate_keys (previously
  duplicated as private helpers inside each basket-* tool).
- load_basket(path) / save_basket(path, data). Both abort via
  `_common.die()` on unrecoverable errors (missing file, invalid
  JSON, duplicate keys) so callers never grow the same
  `if not success: sys.exit()` dance again.

basket-remove-uuids:
- Drop the unused colorama warn_print / err_print wrappers, the
  dead `skip_plugins` list, the BasketUUIDRemover class wrapper
  (there were only two meaningful methods) and the leftover
  plugin-style `sys.exit(3)` path.
- Use `_basket.load_basket` / `_basket.save_basket`, keep only
  the pure `remove_uuids()` walker.

basket-join:
- Replace the `os.listdir('check-plugins')` / `os.listdir(
  'notification-plugins')` pair with the sorted
  `_common.iter_plugin_dirs()` iterator, which additionally
  respects the SKIP_PLUGINS set. This is a deterministic ordering
  change: the old version's per-plugin order depended on the
  file system (ext4/xfs hash order), so datafield numeric IDs in
  the merged output used to shift between machines; the new
  version always produces the same IDs given the same inputs.
  The set of merged objects is unchanged (same 1938 Datafields,
  293 Commands, 96 DataLists, etc. with identical uuids).
- Replace the colorama err_print / warn_print wrappers with
  `_common.err` / `_common.die` plain-stderr output.
- Drop the skip_plugins hardcoded list now that SKIP_PLUGINS
  lives in _common.

basket-compare:
- Replace the plugin-style `try: parse_args() except SystemExit:
  sys.exit(STATE_UNKNOWN)` / `lib.base.cu()` / `lib.base.oao('')`
  scaffolding with a plain main() that uses `_common.die()` for
  real errors.
- Replace the `exit()` builtin call in `get_service_sets_diff`
  with a proper `_common.die()` so the "unhandled deepdiff
  category" branch actually says what went wrong.
- Clean up `get_val()` so the `d is None` case is handled on the
  first line instead of being overwritten after the type check.
- Fold the five identical "normalise-compare-get_diff-print_table"
  blocks in `main()` into a SECTIONS tuple + loop. 175 lines of
  near-duplicated code drop to ~20, and adding a new Director
  object class is now one SECTIONS entry.

build-basket:
- Drive-by fix caught by the linter sweep: rename the unused
  `*args` / `**kwargs` parameters on `_return_parser_as_tuple`
  to `*_args` / `*_kwargs` so vulture stops flagging them at
  100% confidence. Phase-6 cleanup will touch this tool properly;
  this commit only silences the warning.

Verified:
- `tools/run-linter-checks`: ruff, bandit, vulture all green.
- `tools/basket-join --output-file /tmp/basket-new.json`: exits
  clean, 293 Commands, 1938 Datafields, 96 DataLists - identical
  set and uuids to the pre-refactor run.
- `tools/basket-compare /tmp/basket-new.json /tmp/basket-new.json`:
  exits 0 with no output (self-diff is empty).

Author: markuslf

tools/_basket.py

@@ -0,0 +1,93 @@
+#! /usr/bin/env python3
+# -*- coding: utf-8; py-indent-offset: 4 -*-
+#
+# Author:  Linuxfabrik GmbH, Zurich, Switzerland
+# Contact: info (at) linuxfabrik (dot) ch
+#          https://www.linuxfabrik.ch/
+# License: The Unlicense, see LICENSE file.
+
+# https://github.com/Linuxfabrik/monitoring-plugins/blob/main/CONTRIBUTING.md
+
+"""Shared helpers for the basket-* tools.
+
+Icinga Director basket JSON files are the repo's exchange format for
+Director objects (datafields, commands, host templates, service
+templates, service sets). Every tool under `tools/` that reads or
+writes a basket goes through `load_basket()` / `save_basket()` here
+so the error handling (duplicate keys, missing file, invalid JSON)
+looks identical across tools and the on-disk format (4-space indent,
+trailing newline) stays byte-stable across regenerations.
+"""
+
+import json
+
+import _common
+
+__author__ = 'Linuxfabrik GmbH, Zurich/Switzerland'
+__version__ = '2026041301'
+
+
+class DuplicateKeyError(ValueError):
+    """Raised by `_raise_on_duplicate_keys` when a basket carries two
+    entries under the same key. Director baskets must not contain
+    duplicates - the import fails silently and drops the earlier
+    value if we let json.load() handle it on its own, so we fail
+    fast instead."""
+
+
+def _raise_on_duplicate_keys(ordered_pairs):
+    """object_pairs_hook for json.load that refuses duplicate keys.
+
+    Returns a plain dict on success; raises DuplicateKeyError the
+    moment any key appears twice in the ordered pair list. Use as
+    `json.load(f, object_pairs_hook=_raise_on_duplicate_keys)`.
+    """
+    result = {}
+    for key, value in ordered_pairs:
+        if key in result:
+            raise DuplicateKeyError(f'Duplicate key: {key}')
+        result[key] = value
+    return result
+
+
+def load_basket(path):
+    """Load a Director basket JSON file and return the parsed dict.
+
+    Aborts via `_common.die()` on file-read error, on invalid JSON
+    and on duplicate keys. All three are conditions the caller
+    cannot meaningfully recover from, so every basket-* tool would
+    otherwise grow the same `if not success: sys.exit()` dance
+    around the call.
+    """
+    try:
+        text = path.read_text(encoding='utf-8')
+    except OSError as exc:
+        _common.die(f'basket: cannot read {path}: {exc}')
+    try:
+        return json.loads(text, object_pairs_hook=_raise_on_duplicate_keys)
+    except json.JSONDecodeError as exc:
+        _common.die(f'basket: cannot parse {path}: {exc}')
+    except DuplicateKeyError as exc:
+        _common.die(f'basket: {path}: {exc}')
+
+
+def save_basket(path, data):
+    """Write a Director basket JSON file with the project's style.
+
+    Writes 4-space indent, `(',', ': ')` separators and a trailing
+    newline - matching what existing committed baskets look like,
+    so `git diff` after a regeneration only shows real content
+    changes and not whitespace churn.
+    """
+    try:
+        with path.open('w', encoding='utf-8') as f:
+            json.dump(
+                data,
+                f,
+                sort_keys=False,
+                indent=4,
+                separators=(',', ': '),
+            )
+            f.write('\n')
+    except OSError as exc:
+        _common.die(f'basket: cannot write {path}: {exc}')

tools/_common.py

@@ -34,10 +34,14 @@
 CHECK_PLUGINS_DIR = REPO_ROOT / 'check-plugins'
 TOOLS_DIR = REPO_ROOT / 'tools'
 
-# The `example` plugin is a code skeleton that new plugins are based
-# on; it is not meant to be discovered, tested or shipped. Tools that
-# walk the check-plugins tree should skip it by default.
-SKIP_PLUGINS = frozenset({'example'})
+# Plugins that exist only as code skeletons and must not be included
+# when tools iterate over `check-plugins/` (or its sibling directories
+# for notification/event plugins): `example` is the reference plugin
+# we copy-paste new plugins from, `dummy` is a minimal variant that
+# exercises argparse and the output library without talking to any
+# real data source. Tools that need to sweep the entire tree anyway
+# can pass `skip=frozenset()` to `iter_plugin_dirs()`.
+SKIP_PLUGINS = frozenset({'dummy', 'example'})
 
 
 def err(msg):
@@ -61,21 +65,36 @@ def die(msg, code=1):
     sys.exit(code)
 
 
-def iter_check_plugins(skip=SKIP_PLUGINS):
-    """Yield every `check-plugins/<name>` directory in sorted order.
+def iter_plugin_dirs(subdir, skip=SKIP_PLUGINS):
+    """Yield every `<subdir>/<name>` directory in sorted order.
 
-    Skips any plugin whose name is in `skip` (default: the `example`
-    skeleton). Tools that need a different skip set - for example, to
-    rerun a single plugin that is normally skipped - can pass
-    `skip=frozenset()` to walk the entire tree.
+    `subdir` is relative to the repo root and names one of the
+    plugin families the repo ships - typically `check-plugins`,
+    `notification-plugins` or `event-plugins`. Missing subdirs
+    yield nothing (tools can iterate over all three without
+    having to check for existence first).
 
-    Yields `pathlib.Path` objects, so callers can chain the usual
-    `.name`, `.is_dir()`, `/ "sub"` operations without dragging `os`
-    and `os.path` imports into the caller.
+    Yields `pathlib.Path` objects so callers can chain the usual
+    `.name`, `.is_dir()`, `/ "sub"` operations without dragging
+    `os` and `os.path` imports into the caller.
     """
-    for entry in sorted(CHECK_PLUGINS_DIR.iterdir()):
+    target = REPO_ROOT / subdir
+    if not target.is_dir():
+        return
+    for entry in sorted(target.iterdir()):
         if not entry.is_dir():
             continue
         if entry.name in skip:
             continue
         yield entry
+
+
+def iter_check_plugins(skip=SKIP_PLUGINS):
+    """Yield every `check-plugins/<name>` directory in sorted order.
+
+    Thin wrapper around `iter_plugin_dirs('check-plugins', ...)`
+    that documents the common-case entry point. Skips the
+    `example` / `dummy` skeletons by default; pass
+    `skip=frozenset()` to walk the entire check-plugins tree.
+    """
+    yield from iter_plugin_dirs('check-plugins', skip=skip)