@gakr-gakr/diffs 0.1.0

package/autobot.plugin.json

@@ -0,0 +1,218 @@
+{
+  "id": "diffs",
+  "activation": {
+    "onStartup": true
+  },
+  "name": "Diffs",
+  "description": "Read-only diff viewer and file renderer for agents.",
+  "contracts": {
+    "tools": ["diffs"]
+  },
+  "toolMetadata": {
+    "diffs": {
+      "optional": true
+    }
+  },
+  "skills": ["./skills"],
+  "uiHints": {
+    "viewerBaseUrl": {
+      "label": "Viewer Base URL",
+      "help": "Persistent gateway base URL used for returned viewer links when a tool call does not pass baseUrl."
+    },
+    "defaults.fontFamily": {
+      "label": "Default Font",
+      "help": "Preferred font family name for diff content and headers."
+    },
+    "defaults.fontSize": {
+      "label": "Default Font Size",
+      "help": "Base diff font size in pixels."
+    },
+    "defaults.lineSpacing": {
+      "label": "Default Line Spacing",
+      "help": "Line-height multiplier applied to diff rows."
+    },
+    "defaults.layout": {
+      "label": "Default Layout",
+      "help": "Initial diff layout shown in the viewer."
+    },
+    "defaults.showLineNumbers": {
+      "label": "Show Line Numbers",
+      "help": "Show line numbers by default."
+    },
+    "defaults.diffIndicators": {
+      "label": "Diff Indicator Style",
+      "help": "Choose added/removed indicators style."
+    },
+    "defaults.wordWrap": {
+      "label": "Default Word Wrap",
+      "help": "Wrap long lines by default."
+    },
+    "defaults.background": {
+      "label": "Default Background Highlights",
+      "help": "Show added/removed background highlights by default."
+    },
+    "defaults.theme": {
+      "label": "Default Theme",
+      "help": "Initial viewer theme."
+    },
+    "defaults.fileFormat": {
+      "label": "Default File Format",
+      "help": "Rendered file format for file mode (PNG or PDF)."
+    },
+    "defaults.fileQuality": {
+      "label": "Default File Quality",
+      "help": "Quality preset for PNG/PDF rendering."
+    },
+    "defaults.fileScale": {
+      "label": "Default File Scale",
+      "help": "Device scale factor used while rendering file artifacts."
+    },
+    "defaults.fileMaxWidth": {
+      "label": "Default File Max Width",
+      "help": "Maximum file render width in CSS pixels."
+    },
+    "defaults.mode": {
+      "label": "Default Output Mode",
+      "help": "Tool default when mode is omitted. Use view for canvas/gateway viewer, file for PNG/PDF, or both."
+    },
+    "defaults.ttlSeconds": {
+      "label": "Default Artifact TTL",
+      "help": "Default lifetime in seconds for diff viewer and file artifacts. Maximum: 21600."
+    },
+    "security.allowRemoteViewer": {
+      "label": "Allow Remote Viewer",
+      "help": "Allow non-loopback access to diff viewer URLs when the token path is known."
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "viewerBaseUrl": {
+        "type": "string",
+        "format": "uri",
+        "pattern": "^[Hh][Tt][Tt][Pp][Ss]?://",
+        "not": {
+          "pattern": "[?#]"
+        }
+      },
+      "defaults": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "fontFamily": {
+            "type": "string",
+            "default": "Fira Code"
+          },
+          "fontSize": {
+            "type": "number",
+            "minimum": 10,
+            "maximum": 24,
+            "default": 15
+          },
+          "lineSpacing": {
+            "type": "number",
+            "minimum": 1,
+            "maximum": 3,
+            "default": 1.6
+          },
+          "layout": {
+            "type": "string",
+            "enum": ["unified", "split"],
+            "default": "unified"
+          },
+          "showLineNumbers": {
+            "type": "boolean",
+            "default": true
+          },
+          "diffIndicators": {
+            "type": "string",
+            "enum": ["bars", "classic", "none"],
+            "default": "bars"
+          },
+          "wordWrap": {
+            "type": "boolean",
+            "default": true
+          },
+          "background": {
+            "type": "boolean",
+            "default": true
+          },
+          "theme": {
+            "type": "string",
+            "enum": ["light", "dark"],
+            "default": "dark"
+          },
+          "fileFormat": {
+            "type": "string",
+            "enum": ["png", "pdf"],
+            "default": "png"
+          },
+          "format": {
+            "type": "string",
+            "description": "Deprecated alias for fileFormat.",
+            "enum": ["png", "pdf"]
+          },
+          "fileQuality": {
+            "type": "string",
+            "enum": ["standard", "hq", "print"],
+            "default": "standard"
+          },
+          "fileScale": {
+            "type": "number",
+            "minimum": 1,
+            "maximum": 4
+          },
+          "fileMaxWidth": {
+            "type": "number",
+            "minimum": 640,
+            "maximum": 2400
+          },
+          "imageFormat": {
+            "type": "string",
+            "description": "Deprecated alias for fileFormat.",
+            "enum": ["png", "pdf"]
+          },
+          "imageQuality": {
+            "type": "string",
+            "description": "Deprecated alias for fileQuality.",
+            "enum": ["standard", "hq", "print"]
+          },
+          "imageScale": {
+            "type": "number",
+            "description": "Deprecated alias for fileScale.",
+            "minimum": 1,
+            "maximum": 4
+          },
+          "imageMaxWidth": {
+            "type": "number",
+            "description": "Deprecated alias for fileMaxWidth.",
+            "minimum": 640,
+            "maximum": 2400
+          },
+          "mode": {
+            "type": "string",
+            "enum": ["view", "image", "file", "both"],
+            "default": "both"
+          },
+          "ttlSeconds": {
+            "type": "number",
+            "minimum": 1,
+            "maximum": 21600,
+            "default": 1800
+          }
+        }
+      },
+      "security": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "allowRemoteViewer": {
+            "type": "boolean",
+            "default": false
+          }
+        }
+      }
+    }
+  }
+}

package/index.ts

@@ -0,0 +1,11 @@
+import { definePluginEntry } from "./api.js";
+import { diffsPluginConfigSchema } from "./src/config.js";
+import { registerDiffsPlugin } from "./src/plugin.js";
+
+export default definePluginEntry({
+  id: "diffs",
+  name: "Diffs",
+  description: "Read-only diff viewer and PNG/PDF renderer for agents.",
+  configSchema: diffsPluginConfigSchema,
+  register: registerDiffsPlugin,
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@gakr-gakr/diffs",
+  "version": "0.1.0",
+  "description": "AutoBot diff viewer plugin",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/autobot/autobot"
+  },
+  "type": "module",
+  "scripts": {
+    "build:viewer": "bun build src/viewer-client.ts --target browser --format esm --minify --outfile assets/viewer-runtime.js"
+  },
+  "dependencies": {
+    "@pierre/diffs": "1.1.22",
+    "@pierre/theme": "0.0.29",
+    "playwright-core": "1.60.0",
+    "typebox": "1.1.38",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@gakr-gakr/plugin-sdk": "workspace:*"
+  },
+  "autobot": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "install": {
+      "npmSpec": "@gakr-gakr/diffs",
+      "localPath": "extensions/diffs",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.4.30"
+    },
+    "compat": {
+      "pluginApi": ">=2026.5.19"
+    },
+    "build": {
+      "autobotVersion": "2026.5.19",
+      "staticAssets": [
+        {
+          "source": "./assets/viewer-runtime.js",
+          "output": "assets/viewer-runtime.js"
+        }
+      ]
+    },
+    "release": {
+      "publishToClawHub": true,
+      "publishToNpm": true
+    }
+  }
+}

package/runtime-api.ts

@@ -0,0 +1 @@
+export { resolveRequestClientIp } from "autobot/plugin-sdk/webhook-ingress";

package/skills/diffs/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: diffs
+description: Use the diffs tool to produce real, shareable diffs (viewer URL, file artifact, or both) instead of manual edit summaries.
+---
+
+When you need to show edits as a real diff, prefer the `diffs` tool instead of writing a manual summary.
+
+The `diffs` tool accepts either `before` + `after` text, or a unified `patch` string.
+
+Use `mode=view` when you want an interactive gateway-hosted viewer. After the tool returns, use `details.viewerUrl` with the canvas tool via `canvas present` or `canvas navigate`.
+If the deployment uses a loopback trusted proxy (for example Tailscale Serve with `gateway.trustedProxies` including `127.0.0.1`), raw loopback viewer requests can fail closed without forwarded client-IP headers. In that topology, prefer `mode=file` / `mode=both`, or use a configured `viewerBaseUrl` / explicit proxy/public `baseUrl` when you need a shareable viewer URL.
+
+Use `mode=file` when you need a rendered file artifact. Set `fileFormat=png` (default) or `fileFormat=pdf`. The tool result includes `details.filePath`.
+
+For large or high-fidelity files, use `fileQuality` (`standard`|`hq`|`print`) and optionally override `fileScale`/`fileMaxWidth`.
+
+When you need to deliver the rendered file to a user or channel, do not rely on the raw tool-result renderer. Instead, call the `message` tool and pass `details.filePath` through `path` or `filePath`.
+
+Use `mode=both` when you want both the gateway viewer URL and the rendered artifact.
+
+If the user has configured diffs plugin defaults, prefer omitting `mode`, `theme`, `layout`, and related presentation options unless you need to override them for this specific diff.
+
+Include `path` for before/after text when you know the file name.