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

package/dist/permissions.js

@@ -0,0 +1,271 @@
+import { POLICY_HOOKS } from "./hooks.js";
+import { UI_ICONS } from "./ui.js";
+/** hook 挂载点（封闭列表，见总设计 2.4）。 */
+export const HOOK_MOUNT_POINTS = [
+    "session.start",
+    "session.end",
+    "agent.preStep",
+    "model.request",
+    "model.response",
+    "tool.preExecute",
+    "tool.postExecute",
+    "usage.report",
+];
+const HOOKS = new Set(HOOK_MOUNT_POINTS);
+/** A platform API not declared in the manifest was used. */
+export class ExtensionPermissionError extends Error {
+    constructor(plugin, what) {
+        super(`extension ${plugin}: not allowed; declare "${what}" in the extension manifest`);
+        this.name = "ExtensionPermissionError";
+    }
+}
+/** The consumed extension point is unavailable (not installed, not enabled, or not enabled in that org). */
+export class ExtensionPointUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ExtensionPointUnavailableError";
+    }
+}
+const KEYS = new Set([
+    "secrets",
+    "http",
+    "tools",
+    "hooks",
+    "policyHooks",
+    "models",
+    "storage",
+    "network",
+    "ui",
+]);
+const POLICY = new Set(POLICY_HOOKS);
+const METHODS = new Set(["GET", "POST", "PUT", "DELETE"]);
+const DOMAIN_RE = /^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/i;
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+function strList(label, v, errs) {
+    if (!Array.isArray(v)) {
+        errs.push(`${label} must be an array`);
+        return [];
+    }
+    const out = [];
+    for (const x of v) {
+        if (typeof x !== "string" || x === "")
+            errs.push(`${label} entries must be non-empty strings`);
+        else if (out.includes(x))
+            errs.push(`${label} has duplicate entry "${x}"`);
+        else
+            out.push(x);
+    }
+    return out;
+}
+/** 校验权限清单，返回错误列表（空表示合法）。 */
+export function validatePermissions(plugin, p) {
+    if (p === undefined)
+        return [];
+    if (!isObj(p))
+        return ["permissions must be an object"];
+    const errs = [];
+    for (const k of Object.keys(p)) {
+        if (!KEYS.has(k))
+            errs.push(`unknown permissions key "${k}"`);
+    }
+    for (const k of ["secrets", "storage"]) {
+        if (p[k] !== undefined && typeof p[k] !== "boolean") {
+            errs.push(`permissions.${k} must be a boolean`);
+        }
+    }
+    if (p.tools !== undefined)
+        strList("permissions.tools", p.tools, errs);
+    if (p.hooks !== undefined) {
+        for (const h of strList("permissions.hooks", p.hooks, errs)) {
+            if (!HOOKS.has(h)) {
+                errs.push(`permissions.hooks has unknown hook "${h}" (allowed: ${HOOK_MOUNT_POINTS.join(", ")})`);
+            }
+        }
+    }
+    if (p.policyHooks !== undefined) {
+        const declared = Array.isArray(p.hooks) ? p.hooks : [];
+        for (const h of strList("permissions.policyHooks", p.policyHooks, errs)) {
+            if (!POLICY.has(h)) {
+                errs.push(`permissions.policyHooks has "${h}", which takes no policy hooks (allowed: ${POLICY_HOOKS.join(", ")})`);
+            }
+            else if (!declared.includes(h)) {
+                errs.push(`permissions.policyHooks has "${h}", which is missing from permissions.hooks`);
+            }
+        }
+    }
+    if (p.network !== undefined) {
+        for (const d of strList("permissions.network", p.network, errs)) {
+            if (!DOMAIN_RE.test(d))
+                errs.push(`permissions.network entry "${d}" is not a valid domain`);
+        }
+    }
+    if (p.http !== undefined) {
+        if (!Array.isArray(p.http))
+            errs.push("permissions.http must be an array");
+        else {
+            const seen = new Set();
+            for (const r of p.http) {
+                if (!isObj(r) ||
+                    typeof r.method !== "string" ||
+                    !METHODS.has(r.method) ||
+                    typeof r.path !== "string" ||
+                    !r.path.startsWith("/") ||
+                    (r.public !== undefined && typeof r.public !== "boolean")) {
+                    errs.push("permissions.http entries need method GET/POST/PUT/DELETE and a path starting with /");
+                    continue;
+                }
+                const key = `${r.method} ${r.path}`;
+                if (seen.has(key))
+                    errs.push(`permissions.http has duplicate route "${key}"`);
+                seen.add(key);
+            }
+        }
+    }
+    if (p.ui !== undefined) {
+        if (!isObj(p.ui))
+            errs.push("permissions.ui must be an object");
+        else {
+            for (const k of Object.keys(p.ui)) {
+                if (k !== "views" && k !== "embeds")
+                    errs.push(`unknown permissions.ui key "${k}"`);
+            }
+            const views = p.ui.views === undefined ? [] : strList("permissions.ui.views", p.ui.views, errs);
+            const embeds = p.ui.embeds === undefined ? [] : strList("permissions.ui.embeds", p.ui.embeds, errs);
+            for (const id of views) {
+                if (embeds.includes(id))
+                    errs.push(`permissions.ui id "${id}" is in both views and embeds`);
+            }
+        }
+    }
+    if (p.models !== undefined) {
+        if (!Array.isArray(p.models))
+            errs.push("permissions.models must be an array");
+        else {
+            const seen = new Set();
+            for (const m of p.models) {
+                const label = isObj(m) && isObj(m.label) ? m.label : undefined;
+                if (!isObj(m) ||
+                    typeof m.purpose !== "string" ||
+                    (m.kind !== "chat" && m.kind !== "embedding") ||
+                    !label ||
+                    typeof label.zh !== "string" ||
+                    label.zh === "" ||
+                    typeof label.en !== "string" ||
+                    label.en === "") {
+                    errs.push("permissions.models entries need purpose, kind chat/embedding and label zh/en");
+                    continue;
+                }
+                if (!m.purpose.startsWith(`${plugin}.`) || m.purpose.length === plugin.length + 1) {
+                    errs.push(`permissions.models purpose "${m.purpose}" must start with "${plugin}."`);
+                }
+                if (seen.has(m.purpose))
+                    errs.push(`permissions.models has duplicate purpose "${m.purpose}"`);
+                seen.add(m.purpose);
+            }
+        }
+    }
+    return errs;
+}
+const UI_ID_RE = /^[a-z][a-z0-9-]{0,39}$/;
+const UI_TITLE_MAX = 100;
+const UI_PLACES = [
+    "conversation",
+    "panel",
+    "section",
+    "inline",
+    "page",
+    "file-preview",
+];
+const UI_EMBED_PREFIX = "/ui/";
+/**
+ * 校验清单 `ui` 并与权限清单交叉核对，返回错误列表（空表示合法）：
+ * 每个贡献的 id 恰好出现在 `permissions.ui.views`（kind view）或 `permissions.ui.embeds`（kind embed）里，
+ * `permissions.ui` 里也不能有清单 `ui` 没有的 id；embed 的 path 以 `/ui/` 开头并在 `permissions.http` 中声明为 GET。
+ * 假定 `permissions` 已经过 {@link validatePermissions}。
+ */
+export function validateUiContributions(ui, permissions) {
+    const perms = isObj(permissions) ? permissions : {};
+    const pui = isObj(perms.ui) ? perms.ui : {};
+    const listed = (k) => Array.isArray(pui[k])
+        ? pui[k].filter((x) => typeof x === "string")
+        : [];
+    const views = listed("views");
+    const embeds = listed("embeds");
+    const gets = new Set((Array.isArray(perms.http) ? perms.http : [])
+        .filter((r) => isObj(r) && r.method === "GET")
+        .map((r) => r.path));
+    const errs = [];
+    const contributions = [];
+    if (ui !== undefined) {
+        if (!Array.isArray(ui))
+            errs.push("ui must be an array");
+        else
+            contributions.push(...ui);
+    }
+    const seen = new Map();
+    const aliases = [];
+    contributions.forEach((c, i) => {
+        const at = `ui[${i}]`;
+        if (!isObj(c)) {
+            errs.push(`${at} must be an object`);
+            return;
+        }
+        if (typeof c.id !== "string" || !UI_ID_RE.test(c.id)) {
+            errs.push(`${at}.id must match ${UI_ID_RE}`);
+            return;
+        }
+        const id = c.id;
+        const title = isObj(c.title) ? c.title : undefined;
+        if (!title ||
+            [title.zh, title.en].some((t) => typeof t !== "string" || t === "" || t.length > UI_TITLE_MAX))
+            errs.push(`ui "${id}" title needs non-empty zh and en of at most ${UI_TITLE_MAX} characters`);
+        if (!UI_PLACES.includes(c.place))
+            errs.push(`ui "${id}" place must be one of ${UI_PLACES.join(", ")}`);
+        if (c.kind !== "view" && c.kind !== "embed") {
+            errs.push(`ui "${id}" kind must be view or embed`);
+            return;
+        }
+        if (c.icon !== undefined && !UI_ICONS.includes(c.icon))
+            errs.push(`ui "${id}" icon must be one of ${UI_ICONS.join(", ")}`);
+        if (c.aliasOf !== undefined)
+            aliases.push({ id, kind: c.kind, target: c.aliasOf });
+        if (seen.has(id))
+            errs.push(`ui has duplicate id "${id}"`);
+        seen.set(id, c.kind);
+        if (c.kind === "view") {
+            if (c.place === "file-preview")
+                errs.push(`ui "${id}" place file-preview is only allowed for kind embed`);
+            if (c.path !== undefined)
+                errs.push(`ui "${id}" path is only allowed for kind embed`);
+            if (!views.includes(id))
+                errs.push(`ui "${id}" (view) must be listed in permissions.ui.views`);
+            return;
+        }
+        if (!embeds.includes(id))
+            errs.push(`ui "${id}" (embed) must be listed in permissions.ui.embeds`);
+        if (typeof c.path !== "string" || !c.path.startsWith(UI_EMBED_PREFIX)) {
+            errs.push(`ui "${id}" (embed) path must start with "${UI_EMBED_PREFIX}"`);
+        }
+        else if (!gets.has(c.path)) {
+            errs.push(`ui "${id}" (embed) path must be declared in permissions.http as "GET ${c.path}"`);
+        }
+    });
+    const aliasIds = new Set(aliases.map((a) => a.id));
+    for (const a of aliases) {
+        if (typeof a.target !== "string" ||
+            a.target === a.id ||
+            aliasIds.has(a.target) ||
+            seen.get(a.target) !== a.kind)
+            errs.push(`ui "${a.id}" aliasOf must name another, non-alias ${a.kind} contribution`);
+    }
+    for (const [k, kind, ids] of [
+        ["views", "view", views],
+        ["embeds", "embed", embeds],
+    ]) {
+        for (const id of ids) {
+            if (seen.get(id) !== kind)
+                errs.push(`permissions.ui.${k} entry "${id}" has no matching ${kind} contribution in ui`);
+        }
+    }
+    return errs;
+}

package/dist/plugin-manifest.d.ts

@@ -0,0 +1,141 @@
+import { z } from "zod";
+import { type ConnectorTemplateSpec, type LocalizedName, type StaticExtensionManifest } from "./plugin-package.js";
+/**
+ * The plugin manifest `.capybara-plugin/plugin.json` (package ecosystem spec §4.1). A plugin is a
+ * bundle of at most one extension, skills and connector templates, packed as an npm-pack tgz:
+ *
+ * ```
+ * package/package.json                  npm metadata; version equals plugin.json version
+ * package/.capybara-plugin/plugin.json  this manifest (the packer writes it into every tgz)
+ * package/skills/<name>/SKILL.md        skills
+ * package/connectors/<id>.json          connector templates ({@link ConnectorTemplateFile})
+ * package/agents/<name>.md              agent templates (parsed by `parseAgentTemplate`)
+ * package/dist/index.mjs                extension entry (only with an extension)
+ * package/migrations/*.sql, package/ui/**
+ * ```
+ *
+ * Paths start with `./` and stay inside the plugin root. Omitting `skills` / `connectorTemplates`
+ * / `agents` means "scan `skills/*\/SKILL.md` / `connectors/*.json` / `agents/*.md`" (done by the
+ * kernel when it reads the package). `extension` is written by the packer, never by hand.
+ *
+ * The committed JSON Schema (`schemas/plugin.v1.schema.json`) is generated from
+ * {@link PluginManifestSchema} by `pnpm gen:package-schemas` and drift-checked by
+ * `check:package-schemas`. Rules JSON Schema cannot express (path safety and nesting, uniqueness,
+ * no self-dependency, extension name and version equal to the plugin's, the extension manifest
+ * rules of defineExtension) are decided only by {@link parsePluginManifest}. Unknown keys are
+ * rejected (the manifest is written by the author; a typo should fail, not be ignored).
+ */
+/** Path of the manifest inside the plugin root (and under `package/` in a tgz). */
+export declare const PLUGIN_MANIFEST_FILE = ".capybara-plugin/plugin.json";
+/** Manifest format version. */
+export declare const PLUGIN_MANIFEST_SCHEMA_VERSION = 1;
+/** Limits of the plugin manifest. */
+export declare const PLUGIN_MANIFEST_LIMITS: {
+    /** Characters of the `plugin.json` text (larger text is not parsed). */
+    readonly manifestChars: number;
+    readonly dependencies: 20;
+    readonly skills: 50;
+    readonly connectorTemplates: 20;
+    /** Agent templates ({@link AGENT_TEMPLATE_LIMITS}`.perPlugin`). */
+    readonly agents: 64;
+    readonly descriptionChars: 1024;
+    readonly publisherChars: 100;
+    readonly displayNameChars: 100;
+    readonly pathChars: 512;
+};
+/** A plugin this one depends on: a plugin name and a semver range. */
+export interface PluginDependency {
+    /** Catalog item name (`^[a-z0-9][a-z0-9-]{0,63}$`). */
+    name: string;
+    /** semver range. */
+    version: string;
+}
+/** A skill of the plugin: a `./…` directory holding SKILL.md. */
+export interface PluginSkillRef {
+    path: string;
+    /** Suggested as pinned when an agent selects the skill (spec §9.1). */
+    pinned?: boolean;
+}
+/** A connector template of the plugin: a `./…/<id>.json` file ({@link ConnectorTemplateFile}). */
+export interface PluginConnectorTemplateRef {
+    path: string;
+}
+/** An agent template of the plugin: a `./…/<name>.md` file (see `parseAgentTemplate`). */
+export interface PluginAgentRef {
+    path: string;
+}
+/** The plugin's extension, written by the packer. */
+export interface PluginExtensionSection {
+    /** `./dist/index.mjs`. */
+    entry: string;
+    /** The static extension manifest (checked against the module's at load: `manifest_mismatch`). */
+    manifest: StaticExtensionManifest;
+    /** `./migrations`. */
+    migrations?: string;
+    /** `./ui`. */
+    ui?: string;
+}
+/** `.capybara-plugin/plugin.json`. */
+export interface PluginManifest {
+    $schema?: string;
+    schemaVersion: 1;
+    /** Catalog item name; with an extension also an extension name, equal to `extension.manifest.name`. */
+    name: string;
+    /** Exact semver version. */
+    version: string;
+    publisher: string;
+    /** ≤ 1024 characters. */
+    description: string;
+    displayName?: LocalizedName;
+    /** `./…` .svg / .png inside the plugin. */
+    icon?: string;
+    license?: string;
+    /** https URL. */
+    homepage?: string;
+    /** No self-dependency, no duplicates. */
+    dependencies?: PluginDependency[];
+    /** Omitted = scan `skills/*\/SKILL.md`. */
+    skills?: PluginSkillRef[];
+    /** Omitted = scan `connectors/*.json`. */
+    connectorTemplates?: PluginConnectorTemplateRef[];
+    /** Agent templates; omitted = scan `agents/*.md`. */
+    agents?: PluginAgentRef[];
+    extension?: PluginExtensionSection;
+}
+/** A connector template file `connectors/<id>.json`; the template id is the file's base name. */
+export interface ConnectorTemplateFile {
+    displayName: LocalizedName;
+    description?: string;
+    /** Safe path relative to the plugin root (an optional leading `./`), .svg / .png. */
+    icon?: string;
+    /** Validated by {@link validateConnectorTemplate}. */
+    template: ConnectorTemplateSpec;
+}
+/**
+ * The zod schema of `plugin.json` (strict objects: unknown keys rejected, `$schema` allowed).
+ * The JSON Schema is generated with `z.toJSONSchema(PluginManifestSchema, { io: "input" })`.
+ */
+export declare const PluginManifestSchema: z.ZodType<PluginManifest>;
+/**
+ * The zod schema of a connector template file (strict). The JSON Schema is generated with
+ * `z.toJSONSchema(ConnectorTemplateFileSchema, { io: "input" })`.
+ */
+export declare const ConnectorTemplateFileSchema: z.ZodType<ConnectorTemplateFile>;
+/**
+ * Parses and validates `plugin.json`: either the parsed JSON value or the file text (text larger
+ * than {@link PLUGIN_MANIFEST_LIMITS}`.manifestChars` is not parsed). Invalid input returns
+ * `{ errors }` (`<path>: <reason>`, English, at most 50); never throws. Whether the listed paths
+ * exist, and the "contains something" rule after scanning, are checked by the kernel when it reads
+ * the package.
+ */
+export declare function parsePluginManifest(json: unknown): PluginManifest | {
+    errors: string[];
+};
+/**
+ * Parses and validates a connector template file (`connectors/<id>.json`): the parsed JSON value
+ * or the file text. Template problems come from {@link validateConnectorTemplate} (paths relative
+ * to the template root, values never echoed). Returns `{ errors }` (at most 50); never throws.
+ */
+export declare function parseConnectorTemplateFile(json: unknown): ConnectorTemplateFile | {
+    errors: string[];
+};