plugins: add startupCheck function

quickshell/PLUGINS/ExampleStartupCheck/StartupCheck.qml

@@ -0,0 +1,22 @@
+import QtQuick
+import qs.Common
+
+QtObject {
+    // Optional async dependency gate. Receives a done(result) callback:
+    //   done(null)                       -> allow activation
+    //   done("short message")            -> block with a title only
+    //   done({ title, details })         -> block with an expandable details body
+    // A synchronous variant (no argument, return the result) is also supported.
+    function check(done) {
+        Proc.runCommand("exampleStartupCheck.depCheck", ["which", "boregard"], (stdout, exitCode) => {
+            if (exitCode === 0) {
+                done(null);
+                return;
+            }
+            done({
+                "title": I18n.tr("boregard is required"),
+                "details": I18n.tr("The 'boregard' tool is not installed or not on your PATH.\n\nInstall it from https://danklinux.com, then re-enable this plugin.")
+            });
+        });
+    }
+}

quickshell/PLUGINS/ExampleStartupCheck/StartupCheckWidget.qml

@@ -0,0 +1,38 @@
+import QtQuick
+import qs.Common
+import qs.Widgets
+import qs.Modules.Plugins
+
+PluginComponent {
+    id: root
+
+    layerNamespacePlugin: "startup-check"
+
+    horizontalBarPill: Component {
+        Row {
+            spacing: Theme.spacingXS
+
+            DankIcon {
+                name: "verified_user"
+                size: root.iconSize
+                color: Theme.primary
+                anchors.verticalCenter: parent.verticalCenter
+            }
+
+            StyledText {
+                text: "boregard"
+                font.pixelSize: Theme.fontSizeSmall
+                color: Theme.surfaceText
+                anchors.verticalCenter: parent.verticalCenter
+            }
+        }
+    }
+
+    verticalBarPill: Component {
+        DankIcon {
+            name: "verified_user"
+            size: root.iconSize
+            color: Theme.primary
+        }
+    }
+}

quickshell/PLUGINS/ExampleStartupCheck/plugin.json

@@ -0,0 +1,14 @@
+{
+    "id": "exampleStartupCheck",
+    "name": "Startup Check Example",
+    "description": "Demonstrates startupCheck - blocks activation when the 'boregard' dependency is missing",
+    "version": "1.0.0",
+    "author": "AvengeMedia",
+    "type": "widget",
+    "capabilities": ["dankbar-widget"],
+    "component": "./StartupCheckWidget.qml",
+    "startupCheck": "./StartupCheck.qml",
+    "icon": "verified_user",
+    "dependencies": ["boregard"],
+    "permissions": ["process"]
+}

quickshell/PLUGINS/README.md

@@ -557,7 +557,7 @@ PluginService.pluginWidgetComponents: object
 PluginService.loadPlugin(pluginId: string): bool
 PluginService.unloadPlugin(pluginId: string): bool
 PluginService.reloadPlugin(pluginId: string): bool
-PluginService.enablePlugin(pluginId: string): bool
+PluginService.enablePlugin(pluginId: string, onResult?: (ok: bool, error: string) => void): bool
 PluginService.disablePlugin(pluginId: string): bool
 
 // Plugin Discovery
@@ -585,6 +585,41 @@ PluginService.pluginLoadFailed(pluginId: string, error: string)
 PluginService.globalVarChanged(pluginId: string, varName: string)
 ```
 
+## Startup Check (Dependency Gate)
+
+A plugin may optionally gate activation behind a dependency check. Point the manifest's `startupCheck` field at a small, **non-visual** component (a `QtObject` - it must not render in the graphics scene):
+
+```json
+{
+    "startupCheck": "./StartupCheck.qml",
+    "dependencies": ["boregard"]
+}
+```
+
+The component exposes a `check` function that runs before the plugin loads, both on manual enable and on auto-load at startup. Call `done(null)` to allow activation, or `done(error)` to block it. The error can be a short string (title only) or an object with an expandable `details` body for long-form instructions:
+
+```qml
+import QtQuick
+import qs.Common
+
+QtObject {
+    function check(done) {
+        Proc.runCommand("myPlugin.depCheck", ["which", "boregard"], (stdout, exitCode) => {
+            if (exitCode === 0) {
+                done(null)
+                return
+            }
+            done({
+                title: I18n.tr("boregard is required"),
+                details: I18n.tr("Install it from https://danklinux.com, then re-enable this plugin.")
+            })
+        })
+    }
+}
+```
+
+A synchronous variant is supported too - declare `check()` with no argument and return the result directly. When the check fails the enable toggle reverts and the error is shown as a toast (the `details` are expandable, and any `http(s)` URL in them becomes a clickable link). Plugins without a `startupCheck` are unaffected. See `ExampleStartupCheck` for a complete plugin; the last error per plugin is available at `PluginService.pluginLoadErrors[pluginId]`.
+
 ## Plugin Global Variables
 
 Plugins can share state across multiple instances using global variables. This is useful when you have the same widget displayed on multiple monitors or multiple instances of the same widget on different bars.

quickshell/PLUGINS/plugin-schema.json

@@ -98,14 +98,26 @@
       "description": "Path to settings component QML file",
       "pattern": "^\\./.*\\.qml$"
     },
+    "startupCheck": {
+      "type": "string",
+      "description": "Path to a non-visual (QtObject) component exposing a check(done) function that gates activation. done(null) allows; done(error) blocks, where error is a string or { title, details }.",
+      "pattern": "^\\./.*\\.qml$"
+    },
     "requires_dms": {
       "type": "string",
       "description": "Minimum DMS version requirement (e.g., '>=0.1.18', '>0.1.0')",
       "pattern": "^(>=?|<=?|=|>|<)\\d+\\.\\d+\\.\\d+$"
     },
+    "dependencies": {
+      "type": "array",
+      "description": "Array of required system tools/dependencies (registry metadata)",
+      "items": {
+        "type": "string"
+      }
+    },
     "requires": {
       "type": "array",
-      "description": "Array of required system tools/dependencies",
+      "description": "Deprecated alias for 'dependencies'.",
       "items": {
         "type": "string"
       }