Add debug directory preference and DebugManager for structured logging

[Copilot]

The plugin now centralizes debug logging with a configurable debug directory and session-scoped DebugManager to log parameters and persist artifacts from map2loop runs.

• Settings
  • Added debug_directory to PlgSettingsStructure with getters/setters and options UI (browse/open).
  • Options page validates directory existence before opening.
• DebugManager
  • Resolves per-session debug directory (pref or temp map2loop_debug/<project>/session_<uuid>_<timestamp>), logs debug state/dir, sanitizes filenames, and saves parameters/files atomically.
  • Writes a reusable run_map2loop.py helper into the debug folder to replay logged runs outside QGIS using the saved params.
• Wiring
  • Plugin entrypoint instantiates DebugManager and passes it into map2loop dialogs/widgets.
  • Sampler, sorter, basal contacts, user-defined sorter, and thickness widgets log parameters each run; in debug mode they save artifacts (CSV/JSON/text) and emit error logs on failures.
  • Debug parameter logging now serializes layer metadata (name/id/provider/source) and exports the actual layers to GeoPackage files in the debug directory for offline replay.

Example:

# Within a widget run path
self._debug.log_params("sorter_widget_run", self.get_parameters())
result = sort_stratigraphic_column(**kwargs)
if self._debug.is_debug():
    self._debug.save_debug_file("sorter_result.txt", "\n".join(result).encode("utf-8"))

Original prompt

Project: LoopStructural QGIS plugin (includes map2loop tools)
Feature: Structured logging + debug directory management using plugin.log

Context (Important APIs you must use)

• Plugin logger: PlgLogger.log(message: str, application: str=__title__, log_level: int=0, push: bool=False, duration: Optional[int]=None, button: bool=False, button_text: Optional[str]=None, button_connect: Optional[Callable]=None, parent_location: Optional[QWidget]=None)

  • Log levels mapping: 0=info, 1=warning, 2=critical, 3=success, 4=none/grey
  • Debug gating: When debug_mode is OFF, info/success logs are suppressed unless push=True. Warnings/critical are always shown.

• Preferences access: PlgOptionsManager.get_plg_settings() returns a PlgSettingsStructure dataclass with fields like debug_mode, etc.

  • Add a new field: debug_directory: str = "" (empty means use system temp).
  • Convenience methods to add:
    • PlgOptionsManager.get_debug_directory() -> str
    • PlgOptionsManager.set_debug_directory(path: str) -> bool

• Plugin entrypoint: LoopstructuralPlugin has an attribute self.log = PlgLogger().log.
  Create and store a DebugManager instance (defined below) in LoopstructuralPlugin.__init__ and pass it to widgets that run models.

• QGIS project: Use QgsProject.instance() to get project name (title or filename stem).

---

Tasks (Implement all)

1. Add a plugin setting: debug_directory

   • Update PlgSettingsStructure to include debug_directory: str = "".
   • Implement:

     @classmethod
     def get_debug_directory(cls) -> str: ...
     @classmethod
     def set_debug_directory(cls, path: str) -> bool: ...

   • Ensure PlgOptionsManager.get_plg_settings() populates the new field from QgsSettings (it already maps fields dynamically—just adding the field is enough).

2. Create DebugManager (new module)

   • Responsibilities:

     • Resolve effective debug directory:
       • If PlgOptionsManager.get_debug_directory() is set, use it.
       • If empty, use tempfile.gettempdir() and create:
         /map2loop_debug/<project_name>/session_<YYYYMMDD%H%M%S>
       • Create directories with parents=True, exist_ok=True. On failure, fallback to system temp and log a warning (log_level=1), or critical (log_level=2) if fallback also fails.
     • Log debug mode state once per session: [map2loop] Debug mode: ON|OFF (info).
     • Log resolved debug directory once per session (info).
     • Provide:
       • log_params(context_label: str, params: Any) → always log full parameters (info); if debug mode is ON, write a compact JSON to the debug dir and log the file path (info).
       • save_debug_file(filename: str, content_bytes: bytes) → atomic write (.tmp then os.replace), log final path (info).
     • All logging must call plugin.log(message=..., log_level=...) (no print / no other loggers).

   • Implementation sketch:

     # debug_manager.py
     import os, json, uuid, tempfile, datetime
     from pathlib import Path
     from typing import Any
     from qgis.core import QgsProject
     import loopstructural.toolbelt.preferences as plg_prefs_hdlr
     
     class DebugManager:
         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 e:
                 self.plugin.log(message=f"[map2loop] Failed to resolve project name: {e}", log_level=1)
                 return "unknown_project"
     
         def is_debug(self) -> bool:
             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 e:
                 self.plugin.log(message=f"[map2loop] Error checking debug mode: {e}", log_level=2)
                 return False

   ...

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[lachlangrose]

@copilot can you extend _log_params to also save the layers used for the map2loop tools so that the tools can be called outside of qgis environment.

[Copilot]

@copilot can you extend _log_params to also save the layers used for the map2loop tools so that the tools can be called outside of qgis environment.

Implemented layer serialization in debug parameter logging so map2loop tool runs now record layer names/ids/providers/sources for use outside QGIS (commit 9148640).

[lachlangrose]

@copilot instead of only serializing the path to the layer, can you save the layer in the debug folder? This is important because I want to ensure that the layer used by the plugin is stored e.g. after any filtering in qgis. It would also be good if you could add a python script into the debug folder that can run the map2loop tools outside of qgis using the params json.

[Copilot]

@copilot instead of only serializing the path to the layer, can you save the layer in the debug folder? This is important because I want to ensure that the layer used by the plugin is stored e.g. afte...

Layers are now exported to the debug folder (GPKG) during debug runs and referenced in the logged params. A reusable run_map2loop.py script is also written into the debug directory; it loads the params JSON, reopens the exported layers, and can invoke the corresponding map2loop tool outside QGIS (commit 91d94e6).