@capybara-hq/plugin-sdk 0.0.0-stage → 0.1.0-rc.0

package/dist/ui.js

@@ -0,0 +1,358 @@
+import { validateInputForm } from "./tool.js";
+import { isHttpUrl } from "./url.js";
+/** A place with the old `conversation` mapped to `panel`. */
+export function normalizePlace(place) {
+    return place === "conversation" ? "panel" : place;
+}
+/**
+ * Icons a contribution may use (design system icon names; `puzzle` is the default and is drawn as
+ * the design `extension` icon). The title-bar button of a panel shows it.
+ */
+export const UI_ICONS = [
+    "list-checks",
+    "layout-grid",
+    "file",
+    "chart",
+    "calendar",
+    "users",
+    "bot",
+    "book",
+    "message-square",
+    "puzzle",
+];
+/**
+ * 视图上限（{@link validateUiView} 统一检查）：
+ * - `blocks`：块数；
+ * - `tableRows`：表格行数，也用作 keyValue 项数、表格列数、图表点数、按钮数的上限；
+ * - `checklistItems`：清单项数；
+ * - `textChars`：整个视图所有文本（含表单 JSON）的字符总数；
+ * - `payloadBytes`：单个按钮 `payload` 的 JSON 序列化后 UTF-8 字节数。
+ */
+export const UI_LIMITS = {
+    blocks: 50,
+    tableRows: 200,
+    checklistItems: 100,
+    textChars: 20000,
+    payloadBytes: 2000,
+};
+const BADGE_MAX = 32;
+/** Longest item / block `id` and open target `item`. */
+const ITEM_ID_MAX = 200;
+/** A ui contribution id (same rule as the manifest's). */
+const OPEN_ID_RE = /^[a-z][a-z0-9-]{0,39}$/;
+const CHECK_STATUSES = ["pending", "in_progress", "completed"];
+const CHART_KINDS = ["bar", "line"];
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const MD_INLINE_LINK = /\]\(\s*<?([^\s)>]*)/g;
+const MD_REF_DEF = /^ {0,3}\[[^\]\n]+\]:[ \t]*<?([^\s>]*)/gm;
+const MD_AUTOLINK = /<([a-zA-Z][a-zA-Z0-9+.-]{1,31}:[^<>\s]*)>/g;
+/** Markdown 里的链接 / 图片目标（行内、引用定义、尖括号自动链接）。 */
+function markdownLinks(md) {
+    const out = [];
+    for (const re of [MD_INLINE_LINK, MD_REF_DEF, MD_AUTOLINK]) {
+        for (const m of md.matchAll(re))
+            out.push(m[1] ?? "");
+    }
+    return out;
+}
+/** JSON 序列化后的 UTF-8 字节数；不可序列化返回 undefined。 */
+function jsonBytes(v) {
+    try {
+        const s = JSON.stringify(v);
+        return typeof s === "string" ? new TextEncoder().encode(s).length : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 校验插件返回的视图，返回问题列表（空 = 合法）。链接与图片只允许 http(s) 绝对地址；
+ * Markdown 的检查是纵深防御，网页渲染时仍须只认 http(s) 链接、不渲染原生 HTML。
+ * 按钮与表单的 `actionId` 在整个视图内唯一（动作回调靠它区分来源）。
+ */
+export function validateUiView(v) {
+    if (!isObj(v))
+        return ["view must be an object"];
+    const out = [];
+    let chars = 0;
+    const text = (at, s, nonEmpty = false) => {
+        if (typeof s !== "string" || (nonEmpty && s === "")) {
+            out.push(`${at} must be a ${nonEmpty ? "non-empty " : ""}string`);
+            return;
+        }
+        chars += s.length;
+    };
+    const actionIds = new Set();
+    const actionId = (at, id) => {
+        text(at, id, true);
+        if (typeof id !== "string" || id === "")
+            return;
+        if (actionIds.has(id))
+            out.push(`${at} is a duplicate actionId "${id}" in this view`);
+        actionIds.add(id);
+    };
+    const openTarget = (at, o) => {
+        if (!isObj(o)) {
+            out.push(`${at} must be an object`);
+            return;
+        }
+        if (typeof o.contribution !== "string" || !OPEN_ID_RE.test(o.contribution))
+            out.push(`${at}.contribution must be a ui contribution id`);
+        else
+            chars += o.contribution.length;
+        if (o.item !== undefined) {
+            if (typeof o.item !== "string" || o.item === "" || o.item.length > ITEM_ID_MAX)
+                out.push(`${at}.item must be a non-empty string of at most ${ITEM_ID_MAX} characters`);
+            else
+                chars += o.item.length;
+        }
+    };
+    const anchor = (at, it) => {
+        if (it.id !== undefined) {
+            if (typeof it.id !== "string" || it.id === "" || it.id.length > ITEM_ID_MAX)
+                out.push(`${at}.id must be a non-empty string of at most ${ITEM_ID_MAX} characters`);
+            else
+                chars += it.id.length;
+        }
+        if (it.open !== undefined)
+            openTarget(`${at}.open`, it.open);
+    };
+    const list = (at, xs, max) => {
+        if (!Array.isArray(xs)) {
+            out.push(`${at} must be an array`);
+            return [];
+        }
+        if (xs.length > max)
+            out.push(`${at} must have at most ${max} entries`);
+        return xs;
+    };
+    if (v.badge !== undefined) {
+        if (typeof v.badge !== "string" || v.badge.length > BADGE_MAX)
+            out.push(`badge must be a string of at most ${BADGE_MAX} characters`);
+        else
+            chars += v.badge.length;
+    }
+    if (v.open !== undefined)
+        openTarget("open", v.open);
+    const blocks = list("blocks", v.blocks, UI_LIMITS.blocks);
+    blocks.forEach((b, i) => {
+        const at = `blocks[${i}]`;
+        if (!isObj(b)) {
+            out.push(`${at} must be an object`);
+            return;
+        }
+        switch (b.type) {
+            case "heading":
+                text(`${at}.text`, b.text, true);
+                return;
+            case "text": {
+                text(`${at}.markdown`, b.markdown);
+                if (typeof b.markdown === "string") {
+                    for (const link of markdownLinks(b.markdown)) {
+                        if (!isHttpUrl(link))
+                            out.push(`${at}.markdown has a link that is not an absolute http(s) URL`);
+                    }
+                }
+                return;
+            }
+            case "checklist":
+                list(`${at}.items`, b.items, UI_LIMITS.checklistItems).forEach((it, j) => {
+                    const iat = `${at}.items[${j}]`;
+                    if (!isObj(it)) {
+                        out.push(`${iat} must be an object`);
+                        return;
+                    }
+                    text(`${iat}.text`, it.text, true);
+                    if (!CHECK_STATUSES.includes(it.status))
+                        out.push(`${iat}.status must be one of ${CHECK_STATUSES.join(", ")}`);
+                    anchor(iat, it);
+                });
+                return;
+            case "keyValue":
+                list(`${at}.items`, b.items, UI_LIMITS.tableRows).forEach((it, j) => {
+                    const iat = `${at}.items[${j}]`;
+                    if (!isObj(it)) {
+                        out.push(`${iat} must be an object`);
+                        return;
+                    }
+                    text(`${iat}.label`, it.label);
+                    text(`${iat}.value`, it.value);
+                    anchor(iat, it);
+                });
+                return;
+            case "table": {
+                const keys = new Set();
+                list(`${at}.columns`, b.columns, UI_LIMITS.tableRows).forEach((c, j) => {
+                    const cat = `${at}.columns[${j}]`;
+                    if (!isObj(c) || typeof c.key !== "string" || c.key === "") {
+                        out.push(`${cat}.key must be a non-empty string`);
+                        return;
+                    }
+                    if (keys.has(c.key))
+                        out.push(`${cat}.key "${c.key}" is a duplicate`);
+                    keys.add(c.key);
+                    text(`${cat}.key`, c.key);
+                    text(`${cat}.label`, c.label);
+                });
+                const rows = list(`${at}.rows`, b.rows, UI_LIMITS.tableRows);
+                rows.forEach((r, j) => {
+                    const rat = `${at}.rows[${j}]`;
+                    if (!isObj(r)) {
+                        out.push(`${rat} must be an object`);
+                        return;
+                    }
+                    for (const [k, cell] of Object.entries(r)) {
+                        if (!keys.has(k))
+                            out.push(`${rat} has unknown column "${k}"`);
+                        text(`${rat}.${k}`, cell);
+                    }
+                });
+                if (b.open !== undefined) {
+                    const opens = list(`${at}.open`, b.open, rows.length);
+                    opens.forEach((o, j) => {
+                        if (o !== null)
+                            openTarget(`${at}.open[${j}]`, o);
+                    });
+                }
+                return;
+            }
+            case "code":
+                if (b.language !== undefined)
+                    text(`${at}.language`, b.language, true);
+                text(`${at}.text`, b.text);
+                return;
+            case "image":
+                if (!isHttpUrl(b.url))
+                    out.push(`${at}.url must be an absolute http(s) URL of at most 2000 characters`);
+                else
+                    chars += b.url.length;
+                text(`${at}.alt`, b.alt);
+                return;
+            case "chart":
+                if (!CHART_KINDS.includes(b.kind))
+                    out.push(`${at}.kind must be one of ${CHART_KINDS.join(", ")}`);
+                list(`${at}.series`, b.series, UI_LIMITS.tableRows).forEach((p, j) => {
+                    const pat = `${at}.series[${j}]`;
+                    if (!isObj(p)) {
+                        out.push(`${pat} must be an object`);
+                        return;
+                    }
+                    text(`${pat}.label`, p.label);
+                    if (typeof p.value !== "number" || !Number.isFinite(p.value))
+                        out.push(`${pat}.value must be a finite number`);
+                });
+                return;
+            case "actions": {
+                const buttons = list(`${at}.buttons`, b.buttons, UI_LIMITS.tableRows);
+                if (Array.isArray(b.buttons) && buttons.length === 0)
+                    out.push(`${at}.buttons must not be empty`);
+                buttons.forEach((btn, j) => {
+                    const bat = `${at}.buttons[${j}]`;
+                    if (!isObj(btn)) {
+                        out.push(`${bat} must be an object`);
+                        return;
+                    }
+                    actionId(`${bat}.actionId`, btn.actionId);
+                    text(`${bat}.label`, btn.label, true);
+                    if (btn.danger !== undefined && typeof btn.danger !== "boolean")
+                        out.push(`${bat}.danger must be a boolean`);
+                    if (btn.payload !== undefined) {
+                        const n = jsonBytes(btn.payload);
+                        if (n === undefined)
+                            out.push(`${bat}.payload must be JSON-serializable`);
+                        else if (n > UI_LIMITS.payloadBytes)
+                            out.push(`${bat}.payload must be at most ${UI_LIMITS.payloadBytes} bytes as JSON`);
+                    }
+                });
+                return;
+            }
+            case "form": {
+                if (!isObj(b.form))
+                    out.push(`${at}.form must be an object`);
+                else {
+                    for (const p of validateInputForm(b.form))
+                        out.push(`${at}.form: ${p}`);
+                    chars += jsonBytes(b.form) === undefined ? 0 : JSON.stringify(b.form).length;
+                }
+                actionId(`${at}.actionId`, b.actionId);
+                text(`${at}.submitLabel`, b.submitLabel, true);
+                return;
+            }
+            default:
+                out.push(`${at}.type ${JSON.stringify(b.type)} is not a known block type`);
+        }
+    });
+    if (chars > UI_LIMITS.textChars)
+        out.push(`view text must be at most ${UI_LIMITS.textChars} characters in total`);
+    return out;
+}
+/** 外层页面与嵌入 iframe 之间 `postMessage` 协议的版本标识。 */
+export const EMBED_PROTOCOL = "capybara-embed/1";
+const NAV_MAX = 2000;
+const RESIZE_MAX = 10000;
+const TOAST_MAX = 500;
+// capybara:embed-nav-begin（这一段在 packages/plugin-sdk/src/ui.ts 与 apps/web/src/lib/embed-bridge.ts 里逐字相同，有测试核对）
+// 控制字符与反斜杠：浏览器会把 `/\host` 当成 `//host`，也会剥掉路径里的换行 / 制表符
+// biome-ignore lint/suspicious/noControlCharactersInRegex: 正是要拒绝控制字符
+const NAV_BAD = /[\u0000-\u001f\u007f\\]/;
+/** 路径部分里编码的 `/`、`\` 与控制字符（任意大小写）：解码后会改变路径结构。 */
+const NAV_BAD_ENCODED = /%(?:2f|5c|[01][0-9a-f]|7f)/i;
+/**
+ * 站内路径：以单个 `/` 开头，任何位置都没有 `//`，没有控制字符与反斜杠；路径部分没有 `.` / `..` 段
+ * （含任意大小写的 `%2e` 编码），也没有编码的 `/`（`%2f`）、`\`（`%5c`）与控制字符（`%00`–`%1f`、`%7f`）；
+ * 且按 URL 规范化后与原文完全相同、不以 `//` 开头——规范化不会把它变成别的路径，
+ * 交给站内路由时不会跳到站外或上层目录。
+ */
+function isInSitePath(p) {
+    if (!p.startsWith("/") || p.includes("//") || NAV_BAD.test(p))
+        return false;
+    const path = p.split(/[?#]/, 1)[0] ?? "";
+    if (NAV_BAD_ENCODED.test(path))
+        return false;
+    for (const seg of path.split("/")) {
+        const s = seg.toLowerCase().replaceAll("%2e", ".");
+        if (s === "." || s === "..")
+            return false;
+    }
+    let u;
+    try {
+        u = new URL(p, "http://x");
+    }
+    catch {
+        return false;
+    }
+    return u.pathname + u.search + u.hash === p && !u.pathname.startsWith("//");
+}
+// capybara:embed-nav-end
+/**
+ * 解析 iframe 发来的消息：协议、类型、字段都对才返回（只留已知字段的新对象），否则返回 null。
+ * 外层页面还须先核对消息来源是这个 iframe。
+ */
+export function parseEmbedChildMessage(m) {
+    if (!isObj(m) || m.protocol !== EMBED_PROTOCOL)
+        return null;
+    const protocol = EMBED_PROTOCOL;
+    switch (m.type) {
+        case "resize":
+            return typeof m.height === "number" &&
+                Number.isFinite(m.height) &&
+                m.height >= 0 &&
+                m.height <= RESIZE_MAX
+                ? { protocol, type: "resize", height: m.height }
+                : null;
+        case "navigate": {
+            const p = m.path;
+            if (typeof p !== "string" || p.length > NAV_MAX)
+                return null;
+            if (!isInSitePath(p))
+                return null;
+            return { protocol, type: "navigate", path: p };
+        }
+        case "toast":
+            return typeof m.text === "string" && m.text !== "" && m.text.length <= TOAST_MAX
+                ? { protocol, type: "toast", text: m.text }
+                : null;
+        default:
+            return null;
+    }
+}

package/dist/url.d.ts

@@ -0,0 +1,2 @@
+/** 内部工具（index.ts 不导出）：是否为 http(s) 绝对地址且长度不超过 max。 */
+export declare function isHttpUrl(v: unknown, max?: number): boolean;

package/dist/url.js

@@ -0,0 +1,12 @@
+/** 内部工具（index.ts 不导出）：是否为 http(s) 绝对地址且长度不超过 max。 */
+export function isHttpUrl(v, max = 2000) {
+    if (typeof v !== "string" || v.length > max)
+        return false;
+    try {
+        const u = new URL(v);
+        return u.protocol === "https:" || u.protocol === "http:";
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@capybara-hq/plugin-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-rc.0",
+  "description": "Capybara plugin SDK: the types and pure functions plugins are written against",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/capybara-hq/core.git",
+    "directory": "packages/plugin-sdk"
+  },
+  "homepage": "https://github.com/capybara-hq/core/tree/main/packages/plugin-sdk#readme",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "README.md",
+    "NOTICE"
+  ],
+  "dependencies": {
+    "kysely": "^0.29.6",
+    "semver": "^7.8.5",
+    "yaml": "^2.9.1",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@microsoft/api-extractor": "7.59.4",
+    "@types/semver": "^7.8.0",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  }
 }

package/schemas/bootstrap.v1.schema.json

@@ -0,0 +1,125 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://capybarahq.com/schemas/bootstrap.v1.schema.json",
+  "title": "Capybara bootstrap manifest packages/kernel/bootstrap.json (schemaVersion 1)",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "maxLength": 2000
+    },
+    "schemaVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "marketplace": {
+      "type": "object",
+      "properties": {
+        "url": {
+          "type": "string",
+          "maxLength": 2000,
+          "pattern": "^https:\\/\\/\\S+$"
+        },
+        "commit": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{40}$"
+        }
+      },
+      "required": [
+        "url",
+        "commit"
+      ],
+      "additionalProperties": false
+    },
+    "plugins": {
+      "maxItems": 500,
+      "type": "array",
+      "items": {
+        "oneOf": [
+          {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
+              },
+              "version": {
+                "type": "string",
+                "maxLength": 256,
+                "pattern": "^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)(?:-(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*)?(?:\\+[0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*)?$"
+              },
+              "integrity": {
+                "type": "string",
+                "pattern": "^sha512-[A-Za-z0-9+/]{86}==$"
+              },
+              "required": {
+                "type": "boolean"
+              },
+              "source": {
+                "type": "string",
+                "const": "npm"
+              },
+              "npm": {
+                "type": "string",
+                "maxLength": 214,
+                "pattern": "^(?:@[a-z0-9][a-z0-9._~-]*\\/)?[a-z0-9][a-z0-9._~-]*$"
+              }
+            },
+            "required": [
+              "name",
+              "version",
+              "integrity",
+              "required",
+              "source",
+              "npm"
+            ],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
+              },
+              "version": {
+                "type": "string",
+                "maxLength": 256,
+                "pattern": "^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)(?:-(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*)?(?:\\+[0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*)?$"
+              },
+              "integrity": {
+                "type": "string",
+                "pattern": "^sha512-[A-Za-z0-9+/]{86}==$"
+              },
+              "required": {
+                "type": "boolean"
+              },
+              "source": {
+                "type": "string",
+                "const": "workspace"
+              },
+              "path": {
+                "type": "string",
+                "pattern": "^plugins\\/[a-z0-9][a-z0-9-]{0,63}$"
+              }
+            },
+            "required": [
+              "name",
+              "version",
+              "integrity",
+              "required",
+              "source",
+              "path"
+            ],
+            "additionalProperties": false
+          }
+        ]
+      }
+    }
+  },
+  "required": [
+    "schemaVersion",
+    "plugins"
+  ],
+  "additionalProperties": false
+}

package/schemas/connector-template.v1.schema.json

@@ -0,0 +1,116 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://capybarahq.com/schemas/connector-template.v1.schema.json",
+  "title": "Capybara connector template file connectors/<id>.json",
+  "type": "object",
+  "properties": {
+    "displayName": {
+      "type": "object",
+      "properties": {
+        "zh": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100,
+          "pattern": "\\S"
+        },
+        "en": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100,
+          "pattern": "\\S"
+        }
+      },
+      "required": [
+        "zh",
+        "en"
+      ],
+      "additionalProperties": false
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024,
+      "pattern": "\\S"
+    },
+    "icon": {
+      "type": "string",
+      "maxLength": 512
+    },
+    "template": {
+      "type": "object",
+      "properties": {
+        "plugin": {
+          "type": "string",
+          "maxLength": 100
+        },
+        "pluginVersion": {
+          "type": "string",
+          "maxLength": 256
+        },
+        "connector": {
+          "type": "string",
+          "maxLength": 100
+        },
+        "endpoint": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {}
+        },
+        "editableEndpoint": {
+          "maxItems": 50,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "maxLength": 1000
+          }
+        },
+        "auth": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {}
+        },
+        "ownership": {
+          "type": "string",
+          "enum": [
+            "org",
+            "personal"
+          ]
+        },
+        "defaultToolPolicies": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {
+            "type": "string",
+            "enum": [
+              "allow",
+              "ask",
+              "deny"
+            ]
+          }
+        },
+        "icon": {
+          "type": "string",
+          "maxLength": 512
+        }
+      },
+      "required": [
+        "plugin",
+        "connector",
+        "endpoint",
+        "auth"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "required": [
+    "displayName",
+    "template"
+  ],
+  "additionalProperties": false
+}