feat: add debug manager and directory setting

Co-authored-by: lachlangrose <7371904+lachlangrose@users.noreply.github.com>

Author: Copilot

loopstructural/debug_manager.py

@@ -0,0 +1,178 @@
+#! python3
+
+"""Debug manager handling logging and debug directory management."""
+
+# standard
+import datetime
+import json
+import os
+import tempfile
+import uuid
+from pathlib import Path
+from typing import Any
+
+# PyQGIS
+from qgis.core import QgsProject
+
+# project
+import loopstructural.toolbelt.preferences as plg_prefs_hdlr
+
+
+class DebugManager:
+    """Manage debug mode state, logging and debug file storage."""
+
+    def __init__(self, plugin):
+        self.plugin = plugin
+        self._session_dir = None
+        self._session_id = uuid.uuid4().hex
+        self._project_name = self._get_project_name()
+        self._debug_state_logged = False
+
+    def _get_settings(self):
+        return plg_prefs_hdlr.PlgOptionsManager.get_plg_settings()
+
+    def _get_project_name(self) -> str:
+        try:
+            proj = QgsProject.instance()
+            title = proj.title()
+            if title:
+                return title
+            stem = Path(proj.fileName() or "").stem
+            return stem or "untitled_project"
+        except Exception as err:
+            self.plugin.log(
+                message=f"[map2loop] Failed to resolve project name: {err}",
+                log_level=1,
+            )
+            return "unknown_project"
+
+    def is_debug(self) -> bool:
+        """Return whether debug mode is enabled."""
+        try:
+            state = bool(self._get_settings().debug_mode)
+            if not self._debug_state_logged:
+                self.plugin.log(
+                    message=f"[map2loop] Debug mode: {'ON' if state else 'OFF'}",
+                    log_level=0,
+                )
+                self._debug_state_logged = True
+            return state
+        except Exception as err:
+            self.plugin.log(
+                message=f"[map2loop] Error checking debug mode: {err}",
+                log_level=2,
+            )
+            return False
+
+    def get_effective_debug_dir(self) -> Path:
+        """Return the session debug directory, creating it if needed."""
+        if self._session_dir is not None:
+            return self._session_dir
+
+        try:
+            debug_dir_pref = plg_prefs_hdlr.PlgOptionsManager.get_debug_directory()
+        except Exception as err:
+            self.plugin.log(
+                message=f"[map2loop] Reading debug_directory failed: {err}",
+                log_level=1,
+            )
+            debug_dir_pref = ""
+
+        base_dir = (
+            Path(debug_dir_pref).expanduser()
+            if str(debug_dir_pref).strip()
+            else Path(tempfile.gettempdir()) / "map2loop_debug"
+        )
+
+        ts = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
+        session_dir = base_dir / self._project_name / f"session_{self._session_id}_{ts}"
+
+        try:
+            session_dir.mkdir(parents=True, exist_ok=True)
+        except Exception as err:
+            self.plugin.log(
+                message=(
+                    f"[map2loop] Failed to create session dir '{session_dir}': {err}. "
+                    "Falling back to system temp."
+                ),
+                log_level=1,
+            )
+            fallback = (
+                Path(tempfile.gettempdir())
+                / "map2loop_debug"
+                / self._project_name
+                / f"session_{self._session_id}_{ts}"
+            )
+            try:
+                fallback.mkdir(parents=True, exist_ok=True)
+            except Exception as err_fallback:
+                self.plugin.log(
+                    message=(
+                        f"[map2loop] Failed to create fallback debug dir '{fallback}': "
+                        f"{err_fallback}"
+                    ),
+                    log_level=2,
+                )
+                fallback = Path(tempfile.gettempdir())
+            session_dir = fallback
+
+        self._session_dir = session_dir
+        self.plugin.log(
+            message=f"[map2loop] Debug directory resolved: {session_dir}",
+            log_level=0,
+        )
+        return self._session_dir
+
+    def log_params(self, context_label: str, params: Any):
+        """Log parameters and persist them when debug mode is enabled."""
+        try:
+            self.plugin.log(
+                message=f"[map2loop] {context_label} parameters: {params}",
+                log_level=0,
+            )
+        except Exception as err:
+            self.plugin.log(
+                message=(
+                    f"[map2loop] {context_label} parameters (stringified due to {err}): {params}"
+                ),
+                log_level=0,
+            )
+
+        if self.is_debug():
+            try:
+                debug_dir = self.get_effective_debug_dir()
+                safe_label = context_label.replace(" ", "_").lower()
+                file_path = debug_dir / f"{safe_label}_params.json"
+                payload = params if isinstance(params, dict) else {"_payload": params}
+                with open(file_path, "w", encoding="utf-8") as file_handle:
+                    json.dump(payload, file_handle, ensure_ascii=False, indent=2, default=str)
+                self.plugin.log(
+                    message=f"[map2loop] Params saved to: {file_path}",
+                    log_level=0,
+                )
+            except Exception as err:
+                self.plugin.log(
+                    message=f"[map2loop] Failed to save params for {context_label}: {err}",
+                    log_level=2,
+                )
+
+    def save_debug_file(self, filename: str, content_bytes: bytes):
+        """Persist a debug file atomically and log its location."""
+        try:
+            debug_dir = self.get_effective_debug_dir()
+            out_path = debug_dir / filename
+            tmp_path = debug_dir / (filename + ".tmp")
+            with open(tmp_path, "wb") as file_handle:
+                file_handle.write(content_bytes)
+            os.replace(tmp_path, out_path)
+            self.plugin.log(
+                message=f"[map2loop] Debug file saved: {out_path}",
+                log_level=0,
+            )
+            return out_path
+        except Exception as err:
+            self.plugin.log(
+                message=f"[map2loop] Failed to save debug file '{filename}': {err}",
+                log_level=2,
+            )
+            return None

loopstructural/gui/dlg_settings.py

@@ -76,6 +76,11 @@ def __init__(self, parent):
         self.btn_reset.setIcon(QIcon(QgsApplication.iconPath("mActionUndo.svg")))
         self.btn_reset.pressed.connect(self.reset_settings)
 
+        if hasattr(self, "btn_browse_debug_directory"):
+            self.btn_browse_debug_directory.pressed.connect(self._browse_debug_directory)
+        if hasattr(self, "btn_open_debug_directory"):
+            self.btn_open_debug_directory.pressed.connect(self._open_debug_directory)
+
         # load previously saved settings
         self.load_settings()
 
@@ -91,6 +96,9 @@ def apply(self):
         settings.interpolator_cpw = self.cpw_spin_box.value()
         settings.interpolator_regularisation = self.regularisation_spin_box.value()
         settings.version = __version__
+        debug_dir_text = (self.le_debug_directory.text() if hasattr(self, "le_debug_directory") else "") or ""
+        self.plg_settings.set_debug_directory(debug_dir_text)
+        settings.debug_directory = debug_dir_text
 
         # dump new settings into QgsSettings
         self.plg_settings.save_from_object(settings)
@@ -114,6 +122,8 @@ def load_settings(self):
         self.regularisation_spin_box.setValue(settings.interpolator_regularisation)
         self.cpw_spin_box.setValue(settings.interpolator_cpw)
         self.npw_spin_box.setValue(settings.interpolator_npw)
+        if hasattr(self, "le_debug_directory"):
+            self.le_debug_directory.setText(settings.debug_directory or "")
 
     def reset_settings(self):
         """Reset settings in the UI and persisted settings to plugin defaults."""
@@ -125,6 +135,23 @@ def reset_settings(self):
         # update the form
         self.load_settings()
 
+    def _browse_debug_directory(self):
+        """Open a directory selector for debug directory."""
+        from qgis.PyQt.QtWidgets import QFileDialog
+
+        start_dir = (self.le_debug_directory.text() if hasattr(self, "le_debug_directory") else "") or ""
+        chosen = QFileDialog.getExistingDirectory(self, "Select Debug Files Directory", start_dir)
+        if chosen and hasattr(self, "le_debug_directory"):
+            self.le_debug_directory.setText(chosen)
+
+    def _open_debug_directory(self):
+        """Open configured debug directory in the system file manager."""
+        target = self.plg_settings.get_debug_directory() or ""
+        if target:
+            QDesktopServices.openUrl(QUrl.fromLocalFile(target))
+        else:
+            self.log(message="[map2loop] No debug directory configured.", log_level=1)
+
 
 class PlgOptionsFactory(QgsOptionsWidgetFactory):
     """Factory for options widget."""

loopstructural/gui/dlg_settings.ui

@@ -78,9 +78,9 @@
       <bool>false</bool>
      </property>
      <layout class="QGridLayout" name="gridLayout">
-      <item row="8" column="0" colspan="2">
-       <widget class="QPushButton" name="btn_reset">
-        <property name="minimumSize">
+       <item row="9" column="0" colspan="2">
+        <widget class="QPushButton" name="btn_reset">
+         <property name="minimumSize">
          <size>
           <width>200</width>
           <height>25</height>
@@ -100,8 +100,8 @@
         </property>
        </widget>
       </item>
-      <item row="7" column="1">
-       <widget class="QLabel" name="lbl_version_saved_value">
+       <item row="7" column="1">
+        <widget class="QLabel" name="lbl_version_saved_value">
         <property name="minimumSize">
          <size>
           <width>0</width>
@@ -147,8 +147,36 @@
         </property>
        </widget>
       </item>
-      <item row="0" column="0">
-       <widget class="QPushButton" name="btn_help">
+       <item row="8" column="0">
+        <widget class="QLabel" name="lbl_debug_directory">
+         <property name="text">
+          <string>Debug directory</string>
+         </property>
+        </widget>
+       </item>
+       <item row="8" column="1">
+        <layout class="QHBoxLayout" name="horizontalLayout">
+         <item>
+          <widget class="QLineEdit" name="le_debug_directory"/>
+         </item>
+         <item>
+          <widget class="QPushButton" name="btn_browse_debug_directory">
+           <property name="text">
+            <string>Browse...</string>
+           </property>
+          </widget>
+         </item>
+         <item>
+          <widget class="QPushButton" name="btn_open_debug_directory">
+           <property name="text">
+            <string>Open Folder</string>
+           </property>
+          </widget>
+         </item>
+        </layout>
+       </item>
+       <item row="0" column="0">
+        <widget class="QPushButton" name="btn_help">
         <property name="minimumSize">
          <size>
           <width>200</width>

loopstructural/gui/map2loop_tools/basal_contacts_widget.py

@@ -17,7 +17,7 @@ class BasalContactsWidget(QWidget):
     from geology layers.
     """
 
-    def __init__(self, parent=None, data_manager=None):
+    def __init__(self, parent=None, data_manager=None, debug_manager=None):
         """Initialize the basal contacts widget.
 
         Parameters
@@ -29,6 +29,7 @@ def __init__(self, parent=None, data_manager=None):
         """
         super().__init__(parent)
         self.data_manager = data_manager
+        self._debug = debug_manager
 
         # Load the UI file
         ui_path = os.path.join(os.path.dirname(__file__), "basal_contacts_widget.ui")
@@ -62,6 +63,17 @@ def __init__(self, parent=None, data_manager=None):
         # Set up field combo boxes
         self._setup_field_combo_boxes()
 
+    def set_debug_manager(self, debug_manager):
+        """Attach a debug manager instance."""
+        self._debug = debug_manager
+
+    def _log_params(self, context_label: str):
+        if getattr(self, "_debug", None):
+            try:
+                self._debug.log_params(context_label=context_label, params=self.get_parameters())
+            except Exception:
+                pass
+
     def _guess_layers(self):
         """Attempt to auto-select layers based on common naming conventions."""
         if not self.data_manager:
@@ -113,6 +125,8 @@ def _on_geology_layer_changed(self):
 
     def _run_extractor(self):
         """Run the basal contacts extraction algorithm."""
+        self._log_params("basal_contacts_widget_run")
+
         # Validate inputs
         if not self.geologyLayerComboBox.currentLayer():
             QMessageBox.warning(self, "Missing Input", "Please select a geology layer.")
@@ -160,6 +174,16 @@ def _run_extractor(self):
                 "Success",
                 f"Successfully extracted {contact_type}!",
             )
+            if self._debug and self._debug.is_debug():
+                try:
+                    self._debug.save_debug_file(
+                        "basal_contacts_result.txt", str(result).encode("utf-8")
+                    )
+                except Exception as err:
+                    self._debug.plugin.log(
+                        message=f"[map2loop] Failed to save basal contacts debug output: {err}",
+                        log_level=2,
+                    )
 
     def get_parameters(self):
         """Get current widget parameters.