tauri-plugin-debug-tools 0.1.0

package/permissions/schemas/schema.json

@@ -0,0 +1,384 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "PermissionFile",
+  "description": "Permission file that can define a default permission, a set of permissions or a list of inlined permissions.",
+  "type": "object",
+  "properties": {
+    "default": {
+      "description": "The default permission set for the plugin",
+      "anyOf": [
+        {
+          "$ref": "#/definitions/DefaultPermission"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "set": {
+      "description": "A list of permissions sets defined",
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/PermissionSet"
+      }
+    },
+    "permission": {
+      "description": "A list of inlined permissions",
+      "default": [],
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/Permission"
+      }
+    }
+  },
+  "definitions": {
+    "DefaultPermission": {
+      "description": "The default permission set of the plugin.\n\nWorks similarly to a permission with the \"default\" identifier.",
+      "type": "object",
+      "required": [
+        "permissions"
+      ],
+      "properties": {
+        "version": {
+          "description": "The version of the permission.",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint64",
+          "minimum": 1.0
+        },
+        "description": {
+          "description": "Human-readable description of what the permission does. Tauri convention is to use `<h4>` headings in markdown content for Tauri documentation generation purposes.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "permissions": {
+          "description": "All permissions this set contains.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "PermissionSet": {
+      "description": "A set of direct permissions grouped together under a new name.",
+      "type": "object",
+      "required": [
+        "description",
+        "identifier",
+        "permissions"
+      ],
+      "properties": {
+        "identifier": {
+          "description": "A unique identifier for the permission.",
+          "type": "string"
+        },
+        "description": {
+          "description": "Human-readable description of what the permission does.",
+          "type": "string"
+        },
+        "permissions": {
+          "description": "All permissions this set contains.",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/PermissionKind"
+          }
+        }
+      }
+    },
+    "Permission": {
+      "description": "Descriptions of explicit privileges of commands.\n\nIt can enable commands to be accessible in the frontend of the application.\n\nIf the scope is defined it can be used to fine grain control the access of individual or multiple commands.",
+      "type": "object",
+      "required": [
+        "identifier"
+      ],
+      "properties": {
+        "version": {
+          "description": "The version of the permission.",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint64",
+          "minimum": 1.0
+        },
+        "identifier": {
+          "description": "A unique identifier for the permission.",
+          "type": "string"
+        },
+        "description": {
+          "description": "Human-readable description of what the permission does. Tauri internal convention is to use `<h4>` headings in markdown content for Tauri documentation generation purposes.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "commands": {
+          "description": "Allowed or denied commands when using this permission.",
+          "default": {
+            "allow": [],
+            "deny": []
+          },
+          "allOf": [
+            {
+              "$ref": "#/definitions/Commands"
+            }
+          ]
+        },
+        "scope": {
+          "description": "Allowed or denied scoped when using this permission.",
+          "allOf": [
+            {
+              "$ref": "#/definitions/Scopes"
+            }
+          ]
+        },
+        "platforms": {
+          "description": "Target platforms this permission applies. By default all platforms are affected by this permission.",
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "$ref": "#/definitions/Target"
+          }
+        }
+      }
+    },
+    "Commands": {
+      "description": "Allowed and denied commands inside a permission.\n\nIf two commands clash inside of `allow` and `deny`, it should be denied by default.",
+      "type": "object",
+      "properties": {
+        "allow": {
+          "description": "Allowed command.",
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "deny": {
+          "description": "Denied command, which takes priority.",
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "Scopes": {
+      "description": "An argument for fine grained behavior control of Tauri commands.\n\nIt can be of any serde serializable type and is used to allow or prevent certain actions inside a Tauri command. The configured scope is passed to the command and will be enforced by the command implementation.\n\n## Example\n\n```json { \"allow\": [{ \"path\": \"$HOME/**\" }], \"deny\": [{ \"path\": \"$HOME/secret.txt\" }] } ```",
+      "type": "object",
+      "properties": {
+        "allow": {
+          "description": "Data that defines what is allowed by the scope.",
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "$ref": "#/definitions/Value"
+          }
+        },
+        "deny": {
+          "description": "Data that defines what is denied by the scope. This should be prioritized by validation logic.",
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "$ref": "#/definitions/Value"
+          }
+        }
+      }
+    },
+    "Value": {
+      "description": "All supported ACL values.",
+      "anyOf": [
+        {
+          "description": "Represents a null JSON value.",
+          "type": "null"
+        },
+        {
+          "description": "Represents a [`bool`].",
+          "type": "boolean"
+        },
+        {
+          "description": "Represents a valid ACL [`Number`].",
+          "allOf": [
+            {
+              "$ref": "#/definitions/Number"
+            }
+          ]
+        },
+        {
+          "description": "Represents a [`String`].",
+          "type": "string"
+        },
+        {
+          "description": "Represents a list of other [`Value`]s.",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/Value"
+          }
+        },
+        {
+          "description": "Represents a map of [`String`] keys to [`Value`]s.",
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/Value"
+          }
+        }
+      ]
+    },
+    "Number": {
+      "description": "A valid ACL number.",
+      "anyOf": [
+        {
+          "description": "Represents an [`i64`].",
+          "type": "integer",
+          "format": "int64"
+        },
+        {
+          "description": "Represents a [`f64`].",
+          "type": "number",
+          "format": "double"
+        }
+      ]
+    },
+    "Target": {
+      "description": "Platform target.",
+      "oneOf": [
+        {
+          "description": "MacOS.",
+          "type": "string",
+          "enum": [
+            "macOS"
+          ]
+        },
+        {
+          "description": "Windows.",
+          "type": "string",
+          "enum": [
+            "windows"
+          ]
+        },
+        {
+          "description": "Linux.",
+          "type": "string",
+          "enum": [
+            "linux"
+          ]
+        },
+        {
+          "description": "Android.",
+          "type": "string",
+          "enum": [
+            "android"
+          ]
+        },
+        {
+          "description": "iOS.",
+          "type": "string",
+          "enum": [
+            "iOS"
+          ]
+        }
+      ]
+    },
+    "PermissionKind": {
+      "type": "string",
+      "oneOf": [
+        {
+          "description": "Enables the append_debug_logs command without any pre-configured scope.",
+          "type": "string",
+          "const": "allow-append-debug-logs",
+          "markdownDescription": "Enables the append_debug_logs command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the append_debug_logs command without any pre-configured scope.",
+          "type": "string",
+          "const": "deny-append-debug-logs",
+          "markdownDescription": "Denies the append_debug_logs command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the capture_webview_state command without any pre-configured scope.",
+          "type": "string",
+          "const": "allow-capture-webview-state",
+          "markdownDescription": "Enables the capture_webview_state command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the capture_webview_state command without any pre-configured scope.",
+          "type": "string",
+          "const": "deny-capture-webview-state",
+          "markdownDescription": "Denies the capture_webview_state command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the get_console_logs command without any pre-configured scope.",
+          "type": "string",
+          "const": "allow-get-console-logs",
+          "markdownDescription": "Enables the get_console_logs command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the get_console_logs command without any pre-configured scope.",
+          "type": "string",
+          "const": "deny-get-console-logs",
+          "markdownDescription": "Denies the get_console_logs command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the reset_debug_logs command without any pre-configured scope.",
+          "type": "string",
+          "const": "allow-reset-debug-logs",
+          "markdownDescription": "Enables the reset_debug_logs command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the reset_debug_logs command without any pre-configured scope.",
+          "type": "string",
+          "const": "deny-reset-debug-logs",
+          "markdownDescription": "Denies the reset_debug_logs command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the send_debug_command command without any pre-configured scope.",
+          "type": "string",
+          "const": "allow-send-debug-command",
+          "markdownDescription": "Enables the send_debug_command command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the send_debug_command command without any pre-configured scope.",
+          "type": "string",
+          "const": "deny-send-debug-command",
+          "markdownDescription": "Denies the send_debug_command command without any pre-configured scope."
+        },
+        {
+          "description": "Enables the write_debug_snapshot command without any pre-configured scope.",
+          "type": "string",
+          "const": "allow-write-debug-snapshot",
+          "markdownDescription": "Enables the write_debug_snapshot command without any pre-configured scope."
+        },
+        {
+          "description": "Denies the write_debug_snapshot command without any pre-configured scope.",
+          "type": "string",
+          "const": "deny-write-debug-snapshot",
+          "markdownDescription": "Denies the write_debug_snapshot command without any pre-configured scope."
+        },
+        {
+          "description": "Debug tools with official logging and screenshots",
+          "type": "string",
+          "const": "debug-with-logging",
+          "markdownDescription": "Debug tools with official logging and screenshots"
+        },
+        {
+          "description": "Allows debug-tools commands for WebView inspection and log capture.\n\n#### Granted Permissions\n\nAll debug-tools commands are enabled by default.\n\n#### Note\n\nFor full functionality, also enable official plugins:\n- `log:default` for automatic console log collection\n- `screenshots:default` for cross-platform screenshot capture\n\n\n#### This default permission set includes:\n\n- `allow-capture-webview-state`\n- `allow-get-console-logs`\n- `allow-send-debug-command`\n- `allow-append-debug-logs`\n- `allow-reset-debug-logs`\n- `allow-write-debug-snapshot`",
+          "type": "string",
+          "const": "default",
+          "markdownDescription": "Allows debug-tools commands for WebView inspection and log capture.\n\n#### Granted Permissions\n\nAll debug-tools commands are enabled by default.\n\n#### Note\n\nFor full functionality, also enable official plugins:\n- `log:default` for automatic console log collection\n- `screenshots:default` for cross-platform screenshot capture\n\n\n#### This default permission set includes:\n\n- `allow-capture-webview-state`\n- `allow-get-console-logs`\n- `allow-send-debug-command`\n- `allow-append-debug-logs`\n- `allow-reset-debug-logs`\n- `allow-write-debug-snapshot`"
+        }
+      ]
+    }
+  }
+}

package/skills/debug-tauri/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: debug-tauri
+description: Automates Tauri WebView debugging using official plugins (tauri-plugin-log + screenshots) with process verification, automated screenshots, console logs, and state analysis. Use when debugging Tauri apps, investigating WebView issues, analyzing runtime errors, or troubleshooting UI problems.
+---
+
+# Tauri WebView Debugger
+
+Automated debugging workflow for Tauri applications using `tauri-plugin-debug-tools` with official plugin integration.
+
+## Prerequisites
+
+- **tauri-plugin-debug-tools** installed and registered
+- **tauri-plugin-log** (v2.0+): Official logging plugin for automatic console collection
+- **tauri-plugin-screenshots** (v2.0+): Cross-platform screenshot capture
+- Debug permissions enabled: `debug-tools:default`, `log:default`, `screenshots:default`
+- Frontend logger initialized via `attachConsole()` (recommended for automatic log forwarding)
+
+## Quick Start
+
+Run `TAURI_APP_NAME=<app-binary-name> scripts/capture.sh` to verify process and capture screenshot.
+
+If process not found, start your dev server (e.g., `tauri dev`) and retry.
+
+## Debug Workflow
+
+Copy this checklist to track progress:
+
+```markdown
+Debug Progress:
+- [ ] Step 1: Verify process status
+- [ ] Step 2: Capture screenshot
+- [ ] Step 3: Collect console logs
+- [ ] Step 4: Capture WebView state
+- [ ] Step 5: Analyze findings
+- [ ] Step 6: Generate debug report
+- [ ] Step 7: Propose fixes
+```
+
+### Step 1: Verify Process Status
+
+Run: `TAURI_APP_NAME=<your-app> scripts/capture.sh`
+
+This checks if the app is running and captures an initial screenshot.
+
+### Step 2: Capture Screenshot
+
+**Via Plugin API (Recommended)**:
+
+```typescript
+import { captureMainWindow } from "tauri-plugin-debug-tools/screenshotHelper";
+const imagePath = await captureMainWindow();
+```
+
+**Legacy**: capture.sh script (macOS screencapture). See [SCREENSHOTS.md](references/SCREENSHOTS.md) for details.
+
+### Step 3: Collect Console Logs
+
+**Automatic Collection (Recommended)**:
+
+```typescript
+import { logger } from "tauri-plugin-debug-tools/logAdapter";
+
+// Initialize once at app startup
+const detach = await logger.initialize();
+
+// Logs auto-forwarded to platform-specific location
+logger.info("App started");
+logger.error("Something went wrong");
+```
+
+**Log Locations**:
+
+- **macOS**: `~/Library/Logs/{bundle_id}/debug.log`
+- **Linux**: `~/.local/share/{bundle_id}/logs/debug.log`
+- **Windows**: `{LOCALAPPDATA}\{bundle_id}\logs\debug.log`
+
+**Alternative**: Use debugBridge API. See [IPC_COMMANDS.md](references/IPC_COMMANDS.md#console-log-collection) for all methods.
+
+### Step 4: Capture WebView State
+
+```typescript
+import { captureWebViewState } from "tauri-plugin-debug-tools/debugBridge";
+const state = await captureWebViewState();
+```
+
+Returns: `{ url, title, user_agent, viewport }`
+
+### Step 5: Analyze Findings
+
+- **Visual**: Check screenshot for UI issues, errors, layout problems
+- **Logs**: Review errors, warnings, patterns
+- **State**: Verify URL, viewport, user agent
+- **Performance**: Check for memory leaks, high CPU usage
+
+### Step 6: Generate Debug Report
+
+Use template in [REPORT_TEMPLATE.md](references/REPORT_TEMPLATE.md).
+
+### Step 7: Propose Fixes
+
+Based on collected evidence:
+
+- Identify root cause
+- Suggest specific code changes
+- Provide implementation steps
+
+## References
+
+**IPC Commands**: [IPC_COMMANDS.md](references/IPC_COMMANDS.md) - Console logs, WebView state, debug commands
+**Screenshots**: [SCREENSHOTS.md](references/SCREENSHOTS.md) - Capture methods and troubleshooting
+**Troubleshooting**: [TROUBLESHOOTING.md](references/TROUBLESHOOTING.md) - Common errors and solutions
+**Report Template**: [REPORT_TEMPLATE.md](references/REPORT_TEMPLATE.md) - Structured debug report format
+
+**Legacy reference**: `REFERENCE.md` contains combined documentation (will be deprecated)

package/skills/debug-tauri/references/IPC_COMMANDS.md

@@ -0,0 +1,196 @@
+# Tauri IPC Commands Reference
+
+## Table of Contents
+
+- Console Log Collection
+- WebView State Capture
+- Debug Commands
+- Screenshot Commands (Deprecated)
+
+## Console Log Collection
+
+### Method A: Official Plugin (Recommended)
+
+Use `tauri-plugin-log` for automatic console collection with persistence:
+
+```typescript
+import { logger } from "tauri-plugin-debug-tools/logAdapter";
+
+// Initialize once at app startup
+const detach = await logger.initialize();
+
+// All console.* calls are auto-forwarded
+logger.info("App started");
+logger.error("Something went wrong");
+```
+
+**Log Locations**:
+
+- **macOS**: `~/Library/Logs/{bundle_id}/debug.log`
+- **Linux**: `~/.local/share/{bundle_id}/logs/debug.log`
+- **Windows**: `{LOCALAPPDATA}\{bundle_id}\logs\debug.log`
+
+**Analysis**:
+
+```bash
+./scripts/analyze_logs.sh
+```
+
+### Method B: Via debugBridge API (Legacy)
+
+If using custom `consoleLogger` implementation:
+
+```typescript
+import { getConsoleLogs, getConsoleErrors } from "tauri-plugin-debug-tools/debugBridge";
+
+const allLogs = getConsoleLogs();
+const errors = getConsoleErrors();
+```
+
+**Deprecated**: Migrate to Method A (official plugin) for persistence and cross-platform support.
+
+### Method C: Via IPC Command (Not Recommended)
+
+```typescript
+import { invoke } from "@tauri-apps/api/core";
+
+const logs = await invoke("plugin:debug-tools|get_console_logs");
+```
+
+**Note**: Returns empty array. Use Method A (official plugin) instead.
+
+**Fallback**: Only ask user for logs if all automated methods fail.
+
+## WebView State Capture
+
+### capture_webview_state
+
+Retrieves WebView internal state as JSON.
+
+**TypeScript:**
+
+```typescript
+import { captureWebViewState } from "tauri-plugin-debug-tools/debugBridge";
+
+const state = await captureWebViewState();
+console.log(state);
+```
+
+**Response:**
+
+```json
+{
+  "url": "http://localhost:5173",
+  "title": "iori",
+  "user_agent": "TauriWebView/2.0",
+  "viewport": {
+    "width": 1200,
+    "height": 800
+  }
+}
+```
+
+## Debug Commands
+
+### send_debug_command
+
+Send debug commands to WebView (event-based).
+
+**Usage:**
+
+```typescript
+import { sendDebugCommand } from "tauri-plugin-debug-tools/debugBridge";
+
+await sendDebugCommand("get_gpu_state", { includeBuffers: true });
+```
+
+## Screenshot Commands (Deprecated)
+
+### take_screenshot
+
+**Status**: Deprecated. Use system `screencapture` command instead.
+
+**Error message:**
+
+```
+Use system screencapture command instead.
+Run: screencapture -x -T 0 /tmp/tauri_screenshot.png
+```
+
+See [SCREENSHOTS.md](SCREENSHOTS.md) for screenshot capture methods.
+
+## WebGPU Debug API (Planned - Phase 4)
+
+### captureWebGPUState()
+
+Comprehensive WebGPU state capture.
+
+**Returns:**
+
+```typescript
+{
+  deviceInfo: GPUAdapterInfo,
+  bufferStats: {
+    particleBuffer: { size: number, usage: number },
+    uniformBuffer: { size: number, usage: number },
+  },
+  computeResults: Float32Array,
+  performanceMetrics: {
+    fps: number,
+    frameTime: number,
+    memoryUsage: number
+  }
+}
+```
+
+### getDeviceInfo()
+
+Retrieve GPU device information.
+
+```typescript
+const info = await getDeviceInfo();
+// { vendor: "Apple", architecture: "..." }
+```
+
+### exportComputeResults()
+
+Export Compute Shader results to CPU.
+
+```typescript
+const results = await exportComputeResults();
+// Float32Array(100000) - particle position data
+```
+
+### getPerformanceMetrics()
+
+Retrieve performance metrics.
+
+```typescript
+const metrics = await getPerformanceMetrics();
+// { fps: 60, frameTime: 16.67, memoryUsage: 197 }
+```
+
+## Process Information
+
+### Check Running Tauri Process
+
+```bash
+ps aux | grep <app-binary-name> | grep -v grep
+```
+
+**Example output:**
+
+```
+user  94678  1.6  0.3  440546784  197920 s011  S+   11:47AM   0:12.85 target/debug/<app-binary-name>
+```
+
+### Process Details
+
+```bash
+ps -p 94678 -o pid,vsz,rss,%cpu,%mem,command
+```
+
+## References
+
+- [Tauri IPC Commands](https://v2.tauri.app/develop/calling-rust/)
+- [tauri-plugin-debug-tools repository](https://github.com/your-org/tauri-plugin-debug-tools)