Sprint 5: __all__ exports, --doctor CLI, source_url on TweakDef, type-safety fixes, security fixes, improved pre-commit

- Add __all__ to cli, gui, gui_dialogs, gui_theme, gui_tooltip, gui_widgets, menu, deps modules
- Add --doctor CLI command with 7-point health check (Python, winreg, admin, config, tweaks, corpguard, log)
- Add source_url field to TweakDef (optional KB/docs URL reference per tweak)
- Fix _MissingSentinel to inherit from ModuleType (removes type:ignore in deps.py)
- Add None-guards and type-safe attr declarations to TweakRow (gui_widgets.py)
- Add path-traversal security guard to load_plugin() (marketplace.py)
- Add auto-detect system dark/light theme on first run (gui.py)
- Improve pre-commit config: trailing-whitespace, end-of-file, check-yaml/toml/json, large files, LF endings
- Code style: reformatted long lines to ruff 150-char limit across registry.py, tweaks/__init__.py
- Tests: TestDoctor (6 tests), path-traversal tests for marketplace, source_url tests for tweaks

Author: aeger

.pre-commit-config.yaml

@@ -3,15 +3,30 @@ repos:
     rev: v0.11.12
     hooks:
       - id: ruff
-        args: [--fix]
+        args: [--fix, --exit-non-zero-on-fix]
+        types_or: [python, pyi]
       - id: ruff-format
+        types_or: [python, pyi]
   - repo: https://github.com/pre-commit/mirrors-mypy
     rev: v1.16.0
     hooks:
       - id: mypy
-        args: [--strict]
+        args: [--strict, --ignore-missing-imports]
         additional_dependencies: []
         files: ^regilattice/
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-json
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: [--maxkb=500]
+      - id: mixed-line-ending
+        args: [--fix=lf]
   - repo: local
     hooks:
       - id: pytest-smoke

regilattice/cli.py

@@ -37,6 +37,8 @@
     tweaks_for_profile,
 )
 
+__all__ = ["main"]
+
 
 def _confirm(prompt: str) -> bool:
     try:
@@ -311,6 +313,96 @@ def _split_root_for_reg(path: str) -> tuple[int, str]:
     raise ValueError(f"Unsupported registry path: {path}")
 
 
+def _run_doctor() -> int:
+    """Comprehensive system health check — prints a report and returns exit code."""
+    import platform
+
+    checks: list[tuple[str, bool, str]] = []  # (label, passed, detail)
+
+    # 1. Python version
+    vi = sys.version_info
+    py_ok = (vi.major, vi.minor) >= (3, 9)
+    checks.append(("Python >= 3.9", py_ok, f"{vi.major}.{vi.minor}.{vi.micro}"))
+
+    # 2. winreg availability
+    win_ok = is_windows()
+    checks.append(("Windows / winreg", win_ok, platform.system()))
+
+    # 3. Admin status
+    from .elevation import is_admin
+
+    admin_ok = is_admin()
+    checks.append(("Running as admin", admin_ok, "yes" if admin_ok else "no (some tweaks unavailable)"))
+
+    # 4. Config file validity
+    config_detail = "OK"
+    try:
+        from .config import load_config
+
+        load_config(None)
+        cfg_ok = True
+    except Exception as exc:
+        cfg_ok = False
+        config_detail = str(exc)[:80]
+    checks.append(("Config file", cfg_ok, config_detail))
+
+    # 5. Tweaks load cleanly
+    tweak_detail = "OK"
+    try:
+        from .tweaks import all_tweaks
+
+        all_tweaks_list = all_tweaks()
+        ids = [td.id for td in all_tweaks_list]
+        dup_ids = {tid for tid in ids if ids.count(tid) > 1}
+        tweaks_ok = len(dup_ids) == 0
+        tweak_detail = f"{len(all_tweaks_list)} tweaks loaded" if tweaks_ok else f"Duplicate IDs: {', '.join(sorted(dup_ids))}"
+    except Exception as exc:
+        tweaks_ok = False
+        tweak_detail = str(exc)[:80]
+    checks.append(("Tweaks registry", tweaks_ok, tweak_detail))
+
+    # 6. Corporate guard
+    corp_detail = "not detected"
+    try:
+        from .corpguard import corp_guard_status, is_corporate_network
+
+        if is_corporate_network():
+            corp_detail = corp_guard_status() or "corporate network detected"
+        corp_ok = True  # detecting is not a failure; just informational
+    except Exception as exc:
+        corp_ok = False
+        corp_detail = str(exc)[:80]
+    checks.append(("Corp guard", corp_ok, corp_detail))
+
+    # 7. Session log writable
+    try:
+        SESSION.log_path.parent.mkdir(parents=True, exist_ok=True)
+        log_ok = True
+        log_detail = str(SESSION.log_path)
+    except Exception as exc:
+        log_ok = False
+        log_detail = str(exc)[:80]
+    checks.append(("Log path writable", log_ok, log_detail))
+
+    # ── Report ────────────────────────────────────────────────────────────────
+    _W = 30
+    print(f"\n  {'RegiLattice Doctor':^{_W + 20}}")
+    print(f"  {platform_summary()}")
+    print()
+    all_ok = True
+    for label, passed, detail in checks:
+        icon = "\u2705" if passed else "\u274c"
+        all_ok = all_ok and passed
+        print(f"  {icon}  {label:<{_W}}  {detail}")
+    print()
+    if all_ok:
+        print("  All checks passed \u2014 RegiLattice is healthy.")
+    else:
+        print("  \u26a0\ufe0f  Some checks failed. Review the items marked with \u274c above.")
+    print()
+    return 0 if all_ok else 1
+
+
 def _build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="regilattice",
@@ -499,6 +591,11 @@ def _build_parser() -> argparse.ArgumentParser:
         dest="needs_admin",
         help="Show only tweaks that require administrator rights (use with --list/--search).",
     )
+    parser.add_argument(
+        "--doctor",
+        action="store_true",
+        help="Run a comprehensive system health check: Python version, winreg, admin, config, tweaks.",
+    )
     return parser
 
 
@@ -542,6 +639,9 @@ def _handle_shutdown(signum: int, frame: object) -> None:
                 print(f"  \u274c {pkg} \u2014 could not install")
         return 0
 
+    if args.doctor:
+        return _run_doctor()
+
     if args.hwinfo:
         from .hwinfo import detect_hardware, hardware_summary, suggest_profile
 
@@ -716,12 +816,15 @@ def _handle_shutdown(signum: int, frame: object) -> None:
         if getattr(args, "output", "table") == "json":
             import json as _j
 
-            print(_j.dumps(
-                [{"id": td.id, "label": td.label, "category": td.category,
-                  "needs_admin": td.needs_admin, "corp_safe": td.corp_safe}
-                 for td in tweaks],
-                indent=2,
-            ))
+            print(
+                _j.dumps(
+                    [
+                        {"id": td.id, "label": td.label, "category": td.category, "needs_admin": td.needs_admin, "corp_safe": td.corp_safe}
+                        for td in tweaks
+                    ],
+                    indent=2,
+                )
+            )
         else:
             print(f"{'ID':<30} {'Category':<14} {'Status':<14} Label")
             print("-" * 80)

regilattice/deps.py

@@ -104,13 +104,18 @@ def install_package(pip_name: str) -> bool:
 # ── Lazy import ──────────────────────────────────────────────────────────────
 
 
-class _MissingSentinel:
-    """Placeholder for a package that couldn't be imported or installed."""
+class _MissingSentinel(ModuleType):
+    """Placeholder for a package that couldn't be imported or installed.
+
+    Inherits from :class:`types.ModuleType` so the return type of
+    :func:`lazy_import` stays ``ModuleType`` without a ``type: ignore``.
+    """
 
     def __init__(self, name: str) -> None:
+        super().__init__(name)
         self._name = name
 
-    def __getattr__(self, item: str) -> None:
+    def __getattr__(self, item: str) -> object:
         raise ImportError(f"Optional dependency '{self._name}' is not available. Install it manually: pip install {self._name}")
 
 
@@ -152,7 +157,7 @@ def lazy_import(
 
     # Return a sentinel object so that downstream code can still reference
     # the name — it will raise a clear error when actually used.
-    return _MissingSentinel(module_name)  # type: ignore[return-value]
+    return _MissingSentinel(module_name)
 
 
 def require(*packages: str) -> None:

regilattice/gui.py

@@ -49,6 +49,11 @@
 )
 from .tweaks.maintenance import create_restore_point
 
+__all__ = [
+    "RegiLatticeGUI",
+    "launch",
+]
+
 # ── Theme aliases ────────────────────────────────────────────────────────────
 
 _ACCENT = theme.ACCENT
@@ -818,6 +823,10 @@ def _finish_loading(self) -> None:
         self._restore_collapse_state()
         # Restore saved preferences (theme, profile, filters)
         self._restore_preferences()
+        # If no saved preferences exist yet, apply auto-detected system dark/light theme
+        if not _PREFS_FILE.exists():
+            self._theme_var.set("Auto")
+            self._switch_theme("Auto")
         # Kick off status detection
         self._initial_refresh()
 

regilattice/gui_dialogs.py

@@ -17,6 +17,15 @@
 from .registry import SESSION, platform_summary
 from .tweaks import TweakDef, all_tweaks, tweaks_by_category
 
+__all__ = [
+    "export_json_selection",
+    "export_powershell",
+    "import_json_selection",
+    "open_psmodule_manager",
+    "open_scoop_manager",
+    "show_about",
+]
+
 # ── Theme aliases ────────────────────────────────────────────────────────────
 
 _ACCENT = theme.ACCENT
@@ -388,10 +397,7 @@ def _refresh_list() -> None:
         try:
             scope = scope_var.get()
             scope_flag = f"-Scope {scope}" if scope == "CurrentUser" else ""
-            raw = _run_ps(
-                f"Get-InstalledModule {scope_flag} | Sort-Object Name | "
-                "ForEach-Object {{ '{0}  v{1}' -f $_.Name, $_.Version }}"
-            )
+            raw = _run_ps(f"Get-InstalledModule {scope_flag} | Sort-Object Name | ForEach-Object {{{{ '{{0}}  v{{1}}' -f $_.Name, $_.Version }}}}")
             lines = [ln for ln in raw.splitlines() if ln.strip()]
             for ln in lines:
                 listbox.insert("end", ln)
@@ -505,9 +511,16 @@ def _update_action() -> None:
     pop_frame = tk.LabelFrame(dlg, text="Quick Install Popular Modules", bg=_BG, fg=_FG_DIM, font=_FONT_XS)
     pop_frame.pack(fill="x", padx=16, pady=(0, 8))
     popular_modules = [
-        "PSReadLine", "posh-git", "PowerShellGet", "Az",
-        "Microsoft.Graph", "Terminal-Icons", "oh-my-posh",
-        "PSScriptAnalyzer", "Pester", "SqlServer",
+        "PSReadLine",
+        "posh-git",
+        "PowerShellGet",
+        "Az",
+        "Microsoft.Graph",
+        "Terminal-Icons",
+        "oh-my-posh",
+        "PSScriptAnalyzer",
+        "Pester",
+        "SqlServer",
     ]
     for i, mod in enumerate(popular_modules):
         tk.Button(

regilattice/gui_theme.py

@@ -16,6 +16,42 @@
 else:
     winreg = None  # type: ignore[assignment]
 
+__all__ = [
+    "ACCENT",
+    "BG",
+    "BG_SURFACE",
+    "CARD_BG",
+    "CARD_BG_ALT",
+    "CARD_HOVER",
+    "DIM_BG",
+    "ERR_RED",
+    "FG",
+    "FG_DIM",
+    "FONT",
+    "FONT_BOLD",
+    "FONT_CAT",
+    "FONT_SM",
+    "FONT_TITLE",
+    "FONT_XS",
+    "FONT_XS_BOLD",
+    "GPO_ORANGE",
+    "HEADER_BG",
+    "OK_GREEN",
+    "PURPLE",
+    "STATUS_APPLIED",
+    "STATUS_CORP_BLOCKED",
+    "STATUS_DEFAULT",
+    "STATUS_NOT_APPLIED",
+    "STATUS_UNKNOWN",
+    "TEAL",
+    "WARN_YELLOW",
+    "ThemeDict",
+    "available_themes",
+    "current_theme",
+    "detect_system_theme",
+    "set_theme",
+]
+
 # ── Theme data structure ─────────────────────────────────────────────────────
 
 

regilattice/gui_tooltip.py

@@ -9,6 +9,13 @@
 from .corpguard import is_gpo_managed
 from .tweaks import TweakDef, TweakResult
 
+__all__ = [
+    "Tooltip",
+    "build_tooltip_text",
+    "has_recommendation",
+    "parse_description_metadata",
+]
+
 # ── Theme aliases ────────────────────────────────────────────────────────────
 
 _CARD_HOVER = theme.CARD_HOVER