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

package/dist/plugin-manifest.js

@@ -0,0 +1,322 @@
+import semver from "semver";
+import { z } from "zod";
+import { AGENT_TEMPLATE_LIMITS } from "./agent-template.js";
+import { defineExtension, EXTENSION_NAME_RE } from "./define-extension.js";
+import { CATALOG_ITEM_NAME_RE, CONNECTOR_TEMPLATE_LIMITS, isSafePackagePath, SEMVER_VERSION_RE, validateConnectorTemplate, } from "./plugin-package.js";
+import { hasUpperBound } from "./semver-range.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 const PLUGIN_MANIFEST_FILE = ".capybara-plugin/plugin.json";
+/** Manifest format version. */
+export const PLUGIN_MANIFEST_SCHEMA_VERSION = 1;
+/** Limits of the plugin manifest. */
+export const PLUGIN_MANIFEST_LIMITS = {
+    /** Characters of the `plugin.json` text (larger text is not parsed). */
+    manifestChars: 256 * 1024,
+    dependencies: 20,
+    skills: 50,
+    connectorTemplates: 20,
+    /** Agent templates ({@link AGENT_TEMPLATE_LIMITS}`.perPlugin`). */
+    agents: AGENT_TEMPLATE_LIMITS.perPlugin,
+    descriptionChars: 1024,
+    publisherChars: 100,
+    displayNameChars: 100,
+    pathChars: 512,
+};
+const L = PLUGIN_MANIFEST_LIMITS;
+const MAX_ERRORS = 50;
+const ICON_RE = /\.(?:svg|png)$/i;
+const HTTPS_URL_RE = /^https:\/\/\S+$/;
+const text = (max, what) => z
+    .string()
+    .min(1)
+    .max(max)
+    .regex(/\S/, { message: `${what} must not be blank` });
+const localized = z.strictObject({
+    zh: text(L.displayNameChars, "displayName.zh"),
+    en: text(L.displayNameChars, "displayName.en"),
+});
+/** `./<safe path>` (the part after `./` passes {@link isSafePackagePath}). */
+const isDotPath = (p) => p.startsWith("./") && isSafePackagePath(p.slice(2));
+const dotPath = (what) => z
+    .string()
+    .min(3)
+    .max(L.pathChars)
+    .regex(/^\.\//, { message: `${what} must start with "./"` })
+    .refine(isDotPath, {
+    message: `${what} must be a relative path inside the plugin (no "..", no leading "/")`,
+});
+const stripDot = (p) => p.replace(/^\.\//, "");
+/** `connectors/crm.json` → `crm`. */
+const baseId = (p) => (p.split("/").pop() ?? "").replace(/\.json$/, "");
+const configFields = z
+    .array(z.strictObject({ path: z.string().max(1000), secret: z.boolean(), hot: z.boolean() }))
+    .max(1000);
+const staticExtensionManifest = z.strictObject({
+    name: z.string(),
+    version: z.string(),
+    sdk: z.string().max(256),
+    provides: z.array(z.string()),
+    requires: z.array(z.string()),
+    optional: z.array(z.string()),
+    permissions: z.record(z.string(), z.unknown()),
+    ui: z.array(z.record(z.string(), z.unknown())).optional(),
+    config: z.strictObject({ deployment: configFields, org: configFields }),
+});
+const extensionSection = z.strictObject({
+    entry: dotPath("entry").refine((p) => p.endsWith(".mjs"), {
+        message: "entry must be a .mjs file",
+    }),
+    manifest: staticExtensionManifest,
+    migrations: dotPath("migrations").optional(),
+    ui: dotPath("ui").optional(),
+});
+const schema = z
+    .strictObject({
+    $schema: z.string().max(L.pathChars).optional(),
+    schemaVersion: z.literal(PLUGIN_MANIFEST_SCHEMA_VERSION),
+    name: z.string().regex(CATALOG_ITEM_NAME_RE, {
+        message: "name must match ^[a-z0-9][a-z0-9-]{0,63}$",
+    }),
+    version: z
+        .string()
+        .max(256)
+        .regex(SEMVER_VERSION_RE, { message: "version must be an exact semver version" }),
+    publisher: text(L.publisherChars, "publisher"),
+    description: text(L.descriptionChars, "description"),
+    displayName: localized.optional(),
+    icon: dotPath("icon")
+        .regex(ICON_RE, { message: "icon must be a .svg or .png file" })
+        .optional(),
+    license: text(100, "license").optional(),
+    homepage: z
+        .string()
+        .max(2000)
+        .regex(HTTPS_URL_RE, { message: "homepage must be an https URL" })
+        .optional(),
+    dependencies: z
+        .array(z.strictObject({
+        name: z.string().regex(CATALOG_ITEM_NAME_RE, {
+            message: "name must match ^[a-z0-9][a-z0-9-]{0,63}$",
+        }),
+        version: z
+            .string()
+            .min(1)
+            .max(256)
+            .refine((r) => semver.validRange(r) !== null, {
+            message: "version must be a valid semver range",
+        }),
+    }))
+        .max(L.dependencies)
+        .optional(),
+    skills: z
+        .array(z.strictObject({ path: dotPath("path"), pinned: z.boolean().optional() }))
+        .max(L.skills)
+        .optional(),
+    connectorTemplates: z
+        .array(z.strictObject({
+        path: dotPath("path").refine((p) => p.endsWith(".json") && CATALOG_ITEM_NAME_RE.test(baseId(p)), { message: "path must be a <id>.json file with id matching ^[a-z0-9][a-z0-9-]{0,63}$" }),
+    }))
+        .max(L.connectorTemplates)
+        .optional(),
+    agents: z
+        .array(z.strictObject({
+        path: dotPath("path").regex(/\.md$/, { message: "path must be a .md file" }),
+    }))
+        .max(L.agents)
+        .optional(),
+    extension: extensionSection.optional(),
+})
+    .superRefine((m, ctx) => {
+    const issue = (path, message) => ctx.addIssue({ code: "custom", path, message });
+    const names = new Set();
+    m.dependencies?.forEach((d, i) => {
+        if (d.name === m.name)
+            issue(["dependencies", i, "name"], "a plugin cannot depend on itself");
+        if (names.has(d.name))
+            issue(["dependencies", i, "name"], `duplicate dependency ${d.name}`);
+        names.add(d.name);
+    });
+    const dirs = [];
+    m.skills?.forEach((s, i) => {
+        const p = stripDot(s.path);
+        if (dirs.includes(p)) {
+            issue(["skills", i, "path"], `duplicate skill path ${s.path}`);
+            return;
+        }
+        const other = dirs.find((d) => p.startsWith(`${d}/`) || d.startsWith(`${p}/`));
+        if (other !== undefined) {
+            issue(["skills", i, "path"], `skill path ${s.path} is inside another skill (./${other}) or contains it`);
+        }
+        dirs.push(p);
+    });
+    const ids = new Set();
+    m.connectorTemplates?.forEach((c, i) => {
+        const id = baseId(c.path);
+        if (ids.has(id))
+            issue(["connectorTemplates", i, "path"], `duplicate connector template id ${id}`);
+        ids.add(id);
+    });
+    const agentPaths = new Set();
+    m.agents?.forEach((a, i) => {
+        if (agentPaths.has(a.path))
+            issue(["agents", i, "path"], `duplicate agent template path ${a.path}`);
+        agentPaths.add(a.path);
+    });
+    if (m.extension === undefined &&
+        m.skills?.length === 0 &&
+        m.connectorTemplates?.length === 0 &&
+        (m.agents === undefined || m.agents.length === 0)) {
+        issue([], "a plugin must contain an extension, a skill, a connector template or an agent template");
+    }
+    const ext = m.extension;
+    if (ext === undefined)
+        return;
+    const em = ext.manifest;
+    if (!EXTENSION_NAME_RE.test(m.name)) {
+        issue(["name"], `a plugin with an extension needs an extension name (${EXTENSION_NAME_RE})`);
+    }
+    if (em.name !== m.name) {
+        issue(["extension", "manifest", "name"], `extension name "${em.name}" must equal the plugin name "${m.name}"`);
+    }
+    if (em.version !== m.version) {
+        issue(["extension", "manifest", "version"], `extension version "${em.version}" must equal the plugin version "${m.version}"`);
+    }
+    if (semver.validRange(em.sdk) !== null && !hasUpperBound(em.sdk)) {
+        issue(["extension", "manifest", "sdk"], `"${em.sdk}" has no upper bound: use a range such as ^0.1.0 so a future major SDK is not assumed compatible`);
+    }
+    for (const k of ["deployment", "org"]) {
+        const seen = new Set();
+        for (const f of em.config[k]) {
+            if (seen.has(f.path)) {
+                issue(["extension", "manifest", "config", k], `duplicate config path "${f.path}"`);
+            }
+            seen.add(f.path);
+        }
+    }
+    // Name, version, sdk range, extension point refs, permissions, UI contributions: the same
+    // rules as defineExtension (with a placeholder setup).
+    try {
+        defineExtension({
+            ...em,
+            config: undefined,
+            migrations: undefined,
+            setup() { },
+        });
+    }
+    catch (e) {
+        issue(["extension", "manifest"], e instanceof Error ? e.message : String(e));
+    }
+});
+/**
+ * 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 const PluginManifestSchema = schema;
+const template = z.strictObject({
+    plugin: z.string().max(100),
+    pluginVersion: z.string().max(256).optional(),
+    connector: z.string().max(100),
+    endpoint: z.record(z.string(), z.unknown()),
+    editableEndpoint: z
+        .array(z.string().max(1000))
+        .max(CONNECTOR_TEMPLATE_LIMITS.editablePaths)
+        .optional(),
+    auth: z.record(z.string(), z.unknown()),
+    ownership: z.enum(["org", "personal"]).optional(),
+    defaultToolPolicies: z.record(z.string(), z.enum(["allow", "ask", "deny"])).optional(),
+    icon: z.string().max(L.pathChars).optional(),
+});
+const templateFile = z
+    .strictObject({
+    displayName: localized,
+    description: text(CONNECTOR_TEMPLATE_LIMITS.descriptionChars, "description").optional(),
+    icon: z
+        .string()
+        .max(L.pathChars)
+        .refine((p) => isSafePackagePath(stripDot(p)) && ICON_RE.test(p), {
+        message: "icon must be a relative .svg or .png path inside the plugin",
+    })
+        .optional(),
+    template,
+})
+    // Field rules (no credentials, auth presets, editableEndpoint, ...) belong to validateConnectorTemplate.
+    .superRefine((f, ctx) => {
+    for (const e of validateConnectorTemplate(f.template)) {
+        ctx.addIssue({ code: "custom", path: [], message: e });
+    }
+});
+/**
+ * The zod schema of a connector template file (strict). The JSON Schema is generated with
+ * `z.toJSONSchema(ConnectorTemplateFileSchema, { io: "input" })`.
+ */
+export const ConnectorTemplateFileSchema = templateFile;
+function parseWith(zodSchema, json, file) {
+    let data = json;
+    if (typeof json === "string") {
+        if (json.length > L.manifestChars) {
+            return { errors: [`${file} is larger than ${L.manifestChars} characters`] };
+        }
+        try {
+            data = JSON.parse(json.startsWith("\uFEFF") ? json.slice(1) : json);
+        }
+        catch (e) {
+            const first = (e instanceof Error ? e.message : String(e)).split("\n")[0];
+            return { errors: [`${file} is not valid JSON: ${first}`] };
+        }
+    }
+    if (data === null || typeof data !== "object" || Array.isArray(data)) {
+        return { errors: [`${file} must be a JSON object`] };
+    }
+    const r = zodSchema.safeParse(data);
+    if (r.success)
+        return r.data;
+    return {
+        errors: r.error.issues.slice(0, MAX_ERRORS).map((i) => {
+            const path = i.path.map(String).join(".");
+            return path ? `${path}: ${i.message}` : i.message;
+        }),
+    };
+}
+/**
+ * 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 function parsePluginManifest(json) {
+    return parseWith(PluginManifestSchema, json, "plugin.json");
+}
+/**
+ * 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 function parseConnectorTemplateFile(json) {
+    return parseWith(ConnectorTemplateFileSchema, json, "connector template file");
+}

package/dist/plugin-package.d.ts

@@ -0,0 +1,139 @@
+import { type ExtensionManifest } from "./define-extension.js";
+import type { ExtensionPermissions } from "./permissions.js";
+import type { PluginManifest } from "./plugin-manifest.js";
+/**
+ * Plugin package (npm-pack tgz) rules shared by the SDK, the packer and the kernel (spec §4.1). Pure
+ * functions only: the kernel reads the tgz and scans imports, `packages/plugin-tools` packs it. The
+ * manifest is `.capybara-plugin/plugin.json` (plugin-manifest.ts); an extension's static manifest
+ * ({@link StaticExtensionManifest}) is written into it by the packer and compared with the real
+ * module's {@link staticManifestOf} at load (a difference is `manifest_mismatch`). The extension
+ * entry is single-file ESM with third-party dependencies bundled; only {@link HOST_PROVIDED_PACKAGES}
+ * come from the host.
+ */
+/** 宿主提供的包（peerDependencies，安装时链接到宿主副本）；其余三方依赖必须打进 entry。 */
+export declare const HOST_PROVIDED_PACKAGES: readonly ["@capybara-hq/plugin-sdk", "zod"];
+/** npm 安装时会自动执行的脚本：插件包一律不许有（安装不跑脚本，有也是误导）。 */
+export declare const FORBIDDEN_INSTALL_SCRIPTS: readonly ["preinstall", "install", "postinstall", "prepare"];
+/** 静态清单里的一个配置字段（点路径，根即叶子时为空串）。 */
+export interface StaticConfigField {
+    path: string;
+    secret: boolean;
+    hot: boolean;
+}
+/** 插件清单的静态部分（可 JSON 序列化；不含 setup、zod schema、migrations 路径）。 */
+export interface StaticExtensionManifest {
+    name: string;
+    version: string;
+    sdk: string;
+    provides: string[];
+    requires: string[];
+    optional: string[];
+    permissions: ExtensionPermissions;
+    ui?: ExtensionManifest["ui"];
+    config: {
+        deployment: StaticConfigField[];
+        org: StaticConfigField[];
+    };
+}
+/** 入口模块里的一个 import：`name` 是 specifier（非字面量的动态 import 时为空串）。 */
+export interface EntryImport {
+    name: string;
+    dynamic: boolean;
+    literal: boolean;
+}
+/** npm 包名规则（简化）：可带 scope，小写，≤ 214 字符（长度另行检查）。 */
+export declare const NPM_PACKAGE_NAME_RE: RegExp;
+/**
+ * 包内相对路径是否安全：非空、不以 `/` 开头、不含 `\`、控制字符与盘符，没有空段、`.` 与 `..` 段，≤ 1024 字符。
+ */
+export declare function isSafePackagePath(p: string): boolean;
+/**
+ * 核对入口模块的 import（C11）：静态与字面量动态 import 只许 `node:*`、{@link HOST_PROVIDED_PACKAGES}（含子路径）
+ * 与包内相对路径（`./`、`../`；是否越出包外由调用方按文件位置判断）；非字面量的动态 import 一律拒绝。
+ * 返回问题列表（空表示合法）。
+ */
+export declare function checkEntryImports(specifiers: EntryImport[]): string[];
+/**
+ * 真实清单的静态部分：打包时写进 `capybara.manifest`，加载时与包内的比对（`manifest_mismatch`）。
+ * 结果可 JSON 往返（undefined 字段去掉）；配置字段按路径排序。
+ */
+export declare function staticManifestOf(m: ExtensionManifest): StaticExtensionManifest;
+/**
+ * Validates the `package.json` of a plugin tgz against its parsed `.capybara-plugin/plugin.json`
+ * ({@link PluginManifest}), returning the problems (empty when valid): the rules shared with every
+ * plugin package (npm name, semver version, no install scripts, no `gypfile`, no dependency fields,
+ * `peerDependencies` only host packages, a valid `zod` peer range satisfied by `hostZodVersion`),
+ * no `capybara` section, the version equal to the manifest's, and:
+ * - with an extension: `peerDependencies["@capybara-hq/plugin-sdk"]` present and equal to
+ *   `extension.manifest.sdk`, which the host SDK version satisfies (includePrerelease), and
+ *   `main` / `exports` absent or naming `extension.entry` (the packer writes both);
+ * - without one: no `peerDependencies`, `main` or `exports` at all.
+ */
+export declare function validatePluginPackageJsonFor(pkg: unknown, manifest: PluginManifest, hostSdkVersion: string, opts?: {
+    hostZodVersion?: string;
+}): string[];
+/**
+ * Whether the host SDK satisfies an extension's `extension.manifest.sdk` range: the problem
+ * (English), or undefined when it does (an invalid range is reported by the manifest parser).
+ */
+export declare function hostSdkProblem(sdk: string, hostSdkVersion: string): string | undefined;
+/**
+ * 连接器模板（C30）：连接器插件引用 + `Connector.kind` + 端点预设 + 组织可改的端点路径 + 认证预设（不含凭据）+
+ * 默认 ownership + 各工具默认策略 + 图标。组织安装时只能填凭据、客户端 id / secret 与 `editableEndpoint` 里的字段。
+ */
+export interface ConnectorTemplateSpec {
+    /** 连接器插件名（如 `connector-mcp`）。 */
+    plugin: string;
+    /** 连接器插件的 semver 范围，可选。 */
+    pluginVersion?: string;
+    /** `Connector.kind`（如 `"mcp"`）。 */
+    connector: string;
+    /** 端点预设；导入时内核按该连接器的 `endpointSchema` 校验。 */
+    endpoint: Record<string, unknown>;
+    /** 组织安装时允许改的点路径（如 `"url"`）；其余以模板为准。路径必须存在于连接器的端点 schema 中。 */
+    editableEndpoint?: string[];
+    /** 与连接器安装接口的认证方式同形（{@link ConnectorAuthSchema}），不含任何凭据。 */
+    auth: Record<string, unknown>;
+    /** 缺省取 `auth.ownership`；给了就必须与之一致。 */
+    ownership?: "org" | "personal";
+    /** 工具名 → 默认策略（安装后记 `policy_source 'template'`）。 */
+    defaultToolPolicies?: Record<string, "allow" | "ask" | "deny">;
+    /** 包内路径，svg / png，≤ {@link CONNECTOR_TEMPLATE_LIMITS}`.iconBytes`。 */
+    icon?: string;
+}
+/** 双语显示名。 */
+export interface LocalizedName {
+    zh: string;
+    en: string;
+}
+/** 连接器模板与目录段的上限。 */
+export declare const CONNECTOR_TEMPLATE_LIMITS: {
+    /** 图标字节数上限。 */
+    readonly iconBytes: number;
+    /** 端点预设 JSON 序列化后的字符数上限。 */
+    readonly endpointChars: number;
+    /** `editableEndpoint` 条数上限。 */
+    readonly editablePaths: 50;
+    /** `defaultToolPolicies` 条数上限。 */
+    readonly toolPolicies: 1000;
+    /** publisher 字符数上限。 */
+    readonly publisherChars: 100;
+    /** description 字符数上限。 */
+    readonly descriptionChars: 1024;
+    /** displayName 每种语言的字符数上限。 */
+    readonly displayNameChars: 100;
+};
+/** 目录条目名（与清单条目名同一规则）：小写字母或数字开头，之后小写字母、数字、连字符，≤ 64。 */
+export declare const CATALOG_ITEM_NAME_RE: RegExp;
+/** An exact semver version (a regex JSON Schema can use). */
+export declare const SEMVER_VERSION_RE: RegExp;
+/** The sha512 SRI of an npm package tgz: `sha512-<86 base64 chars>==`. */
+export declare const SHA512_INTEGRITY_RE: RegExp;
+/**
+ * 校验连接器模板（{@link ConnectorTemplateSpec}）的静态部分，返回问题列表（空表示合法；路径相对模板根，不回显值）：
+ * 字段齐全、无未知字段；`auth` 符合 {@link ConnectorAuthSchema}（strict：夹带 `token` 等多余字段即拒绝）；
+ * 端点预设里任何层级都不许有凭据样式的键；`editableEndpoint` 是不重复的点路径；`ownership` 与 `auth.ownership`
+ * 一致；默认策略只许 allow / ask / deny；icon 是包内 .svg / .png 路径。
+ * 端点是否符合连接器的 `endpointSchema`、`editableEndpoint` 是否存在于其中，由内核在导入时按已加载的连接器校验。
+ */
+export declare function validateConnectorTemplate(t: unknown): string[];