@zhin.js/adapter-github 3.0.2 → 4.0.0

package/lib/webhook.js

@@ -0,0 +1,87 @@
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { headerValue, parseIssueCommentInbound, parsePrReviewCommentInbound, parsePrReviewInbound, readTextBody, verifyWebhookSignature, } from './protocol.js';
+const logger = getLogger('github');
+export function registerGithubWebhookRoutes(http, handler) {
+    const routePath = handler.config.webhookPath;
+    return [
+        http.route('POST', routePath, async (request, response) => {
+            await handleGithubWebhookRequest(request, response, handler);
+        }, { summary: 'GitHub webhook', tags: ['github'] }),
+    ];
+}
+export async function handleGithubWebhookRequest(request, response, handler) {
+    const secret = handler.config.webhookSecret;
+    if (!secret) {
+        response.writeHead(503, { 'Content-Type': 'application/json' });
+        response.end(JSON.stringify({ error: 'Webhook not configured' }));
+        return;
+    }
+    const signature = headerValue(request.headers, 'x-hub-signature-256');
+    const event = headerValue(request.headers, 'x-github-event');
+    const deliveryId = headerValue(request.headers, 'x-github-delivery');
+    if (!signature || !event) {
+        response.writeHead(400, { 'Content-Type': 'application/json' });
+        response.end(JSON.stringify({ error: 'Missing signature or event header' }));
+        return;
+    }
+    try {
+        const rawBody = await readTextBody(request);
+        if (!verifyWebhookSignature(secret, rawBody, signature)) {
+            logger.warn(formatCompact({
+                op: 'webhook',
+                ok: false,
+                error: 'invalid signature',
+                delivery: deliveryId,
+            }));
+            response.writeHead(401, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ error: 'Invalid signature' }));
+            return;
+        }
+        let payload;
+        try {
+            payload = rawBody ? JSON.parse(rawBody) : {};
+        }
+        catch {
+            response.writeHead(400, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ error: 'Invalid JSON' }));
+            return;
+        }
+        response.writeHead(200, { 'Content-Type': 'application/json' });
+        response.end(JSON.stringify({ ok: true }));
+        void dispatchGithubWebhookPayload(event, payload, handler).catch((e) => {
+            logger.error(`Webhook 事件处理失败 (${event}):`, e);
+        });
+    }
+    catch (error) {
+        logger.error('Webhook error:', error);
+        if (!response.headersSent) {
+            response.writeHead(500, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ error: 'Internal Server Error' }));
+        }
+    }
+}
+export async function dispatchGithubWebhookPayload(event, payload, handler) {
+    if (!payload || typeof payload !== 'object')
+        return;
+    const body = payload;
+    const repo = body.repository?.full_name;
+    logger.debug(`Webhook: ${event}${body.action ? `.${body.action}` : ''} ${repo || ''}`);
+    if (event === 'issue_comment') {
+        const inbound = parseIssueCommentInbound(payload);
+        if (inbound)
+            handler.admit(inbound);
+        return;
+    }
+    if (event === 'pull_request_review_comment') {
+        const inbound = parsePrReviewCommentInbound(payload);
+        if (inbound)
+            handler.admit(inbound);
+        return;
+    }
+    if (event === 'pull_request_review') {
+        const inbound = parsePrReviewInbound(payload);
+        if (inbound)
+            handler.admit(inbound);
+    }
+    // Cross-adapter subscription fan-out deferred (needs multi-adapter send in Runtime).
+}

package/lib/workspace-manager.d.ts

@@ -0,0 +1,21 @@
+import type { GhClient, GitHubBotIdentity } from './gh-client.js';
+/**
+ * 校验 GitHub "owner/name" 全名，防止路径穿越与 git 选项注入。
+ * 返回通过校验的原值，便于调用方直接使用「已消毒」的变量。
+ */
+export declare function assertRepoFullName(repo: string): string;
+/**
+ * 校验 git ref 名称，拒绝选项注入（`-` 前缀）与 git 非法字符。
+ */
+export declare function assertGitRefName(ref: string): string;
+export declare class WorkspaceManager {
+    private readonly gh;
+    private readonly rootDir;
+    constructor(gh: GhClient, rootDir: string);
+    getRepoPath(repo: string): string;
+    private runGit;
+    configureBotGit(repoPath: string, identity: GitHubBotIdentity): Promise<void>;
+    ensureRepo(repo: string): Promise<string>;
+    checkoutBranch(repo: string, branch: string, baseRef: string): Promise<string>;
+    commitAndPush(repo: string, branch: string, message: string): Promise<string>;
+}

package/lib/{src/workspace-manager.js → workspace-manager.js}

@@ -4,6 +4,45 @@
 import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
+const REPO_FULL_NAME_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const GIT_REF_ILLEGAL_CHARS = new Set('~^:?*[\\`;');
+function containsIllegalGitRefCharacter(ref) {
+    return [...ref].some((character) => {
+        const code = character.charCodeAt(0);
+        return code <= 31
+            || code === 127
+            || /\s/u.test(character)
+            || GIT_REF_ILLEGAL_CHARS.has(character);
+    });
+}
+/**
+ * 校验 GitHub "owner/name" 全名，防止路径穿越与 git 选项注入。
+ * 返回通过校验的原值，便于调用方直接使用「已消毒」的变量。
+ */
+export function assertRepoFullName(repo) {
+    if (typeof repo !== 'string' ||
+        !REPO_FULL_NAME_RE.test(repo) ||
+        repo.split('/').some((seg) => seg === '' || seg.startsWith('-') || /^\.+$/.test(seg))) {
+        throw new TypeError(`非法的仓库全名: ${JSON.stringify(repo)}`);
+    }
+    return repo;
+}
+/**
+ * 校验 git ref 名称，拒绝选项注入（`-` 前缀）与 git 非法字符。
+ */
+export function assertGitRefName(ref) {
+    if (typeof ref !== 'string' || ref.length === 0) {
+        throw new TypeError(`非法的 git ref: ${JSON.stringify(ref)}`);
+    }
+    if (ref.startsWith('-') ||
+        ref.includes('..') ||
+        containsIllegalGitRefCharacter(ref) ||
+        ref.endsWith('/') ||
+        ref.endsWith('.')) {
+        throw new TypeError(`非法的 git ref: ${JSON.stringify(ref)}`);
+    }
+    return ref;
+}
 export class WorkspaceManager {
     gh;
     rootDir;
@@ -12,6 +51,7 @@ export class WorkspaceManager {
         this.rootDir = rootDir;
     }
     getRepoPath(repo) {
+        repo = assertRepoFullName(repo);
         const [owner, name] = repo.split('/');
         return path.join(this.rootDir, owner, name);
     }
@@ -47,6 +87,7 @@ export class WorkspaceManager {
         ]).then(() => undefined);
     }
     async ensureRepo(repo) {
+        repo = assertRepoFullName(repo);
         if (!this.gh.isAppAuth) {
             throw new Error('GitHub App 认证未配置，无法托管工作区');
         }
@@ -70,6 +111,9 @@ export class WorkspaceManager {
         return repoPath;
     }
     async checkoutBranch(repo, branch, baseRef) {
+        repo = assertRepoFullName(repo);
+        branch = assertGitRefName(branch);
+        baseRef = assertGitRefName(baseRef);
         const repoPath = await this.ensureRepo(repo);
         const localBranches = await this.runGit(repoPath, ['branch', '--list', branch]);
         if (localBranches.trim()) {
@@ -89,6 +133,8 @@ export class WorkspaceManager {
         return repoPath;
     }
     async commitAndPush(repo, branch, message) {
+        repo = assertRepoFullName(repo);
+        branch = assertGitRefName(branch);
         const repoPath = this.getRepoPath(repo);
         if (!fs.existsSync(repoPath)) {
             throw new Error(`工作区不存在: ${repoPath}，请先 github_prepare_workspace`);
@@ -106,4 +152,3 @@ export class WorkspaceManager {
         return `已 push 到 origin/${branch}`;
     }
 }
-//# sourceMappingURL=workspace-manager.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhin.js/adapter-github",
-  "version": "3.0.2",
-  "description": "Zhin.js adapter for GitHub (gh CLI) — treat issues/PRs as chat channels, full repo management, webhook notifications",
+  "version": "4.0.0",
+  "description": "Zhin.js GitHub adapter for Plugin Runtime (App auth + webhook)",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -18,15 +18,6 @@
     },
     "./package.json": "./package.json"
   },
-  "files": [
-    "src",
-    "lib",
-    "agent",
-    "client",
-    "dist",
-    "plugin.yml",
-    "README.md"
-  ],
   "keywords": [
     "zhin",
     "zhin.js",
@@ -44,21 +35,29 @@
     "url": "https://github.com/lc-cn"
   },
   "license": "MIT",
-  "devDependencies": {
-    "typescript": "^6.0.3",
-    "zod": "^4.4.3",
-    "@zhin.js/agent": "1.0.3",
-    "@zhin.js/host-router": "2.0.3",
-    "zhin.js": "4.1.2"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhinjs/zhin.git",
+    "directory": "plugins/adapters/github"
+  },
+  "dependencies": {
+    "@zhin.js/adapter": "1.1.0",
+    "@zhin.js/core": "1.4.0",
+    "@zhin.js/host-http": "1.0.2",
+    "@zhin.js/logger": "1.0.75",
+    "@zhin.js/plugin-runtime": "1.1.0"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/host-router": "2.0.3",
-    "zhin.js": "4.1.2",
-    "@zhin.js/agent": "1.0.3"
+    "@zhin.js/adapter": "1.1.0",
+    "@zhin.js/agent": "1.0.5",
+    "@zhin.js/core": "1.4.0",
+    "@zhin.js/host-http": "1.0.2",
+    "@zhin.js/plugin-runtime": "1.1.0",
+    "zhin.js": "5.0.0"
   },
   "peerDependenciesMeta": {
-    "@zhin.js/host-router": {
+    "zhin.js": {
       "optional": true
     },
     "@zhin.js/agent": {
@@ -68,11 +67,24 @@
       "optional": true
     }
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/zhinjs/zhin.git",
-    "directory": "plugins/adapters/github"
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10",
+    "zod": "^4.4.3",
+    "@zhin.js/agent": "1.0.5",
+    "zhin.js": "5.0.0"
   },
+  "files": [
+    "adapters",
+    "plugin.ts",
+    "schema.json",
+    "src",
+    "lib",
+    "agent",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
@@ -80,8 +92,23 @@
   "engines": {
     "node": "^20.19.0 || >=22.12.0"
   },
+  "zhin": {
+    "protocol": 1,
+    "type": "plugin",
+    "entry": "./plugin.ts",
+    "engine": "^1.0.0",
+    "runtime": "trusted",
+    "features": [
+      {
+        "package": "@zhin.js/adapter",
+        "api": "^1.0.0"
+      }
+    ],
+    "plugins": []
+  },
   "scripts": {
     "build": "tsc",
-    "clean": "rimraf lib"
+    "clean": "rimraf lib",
+    "test": "NODE_OPTIONS=--experimental-strip-types vitest run --root ../../.. plugins/adapters/github/tests"
   }
 }

package/plugin.ts

@@ -0,0 +1,52 @@
+import { definePlugin, databaseHostToken } from '@zhin.js/plugin-runtime';
+import { defineGithubOauthUsersTable } from './src/oauth-users.js';
+
+/**
+ * github_subscriptions — repo event subscriptions per chat channel
+ * (used by github_subscriptions agent tool; schema matches legacy defineModel).
+ */
+const GITHUB_SUBSCRIPTIONS_SCHEMA = {
+  id: { type: 'integer', primary: true },
+  repo: { type: 'text', nullable: false },
+  events: { type: 'json', default: [] },
+  target_id: { type: 'text', nullable: false },
+  target_type: { type: 'text', nullable: false },
+  adapter: { type: 'text', nullable: false },
+  endpoint: { type: 'text', nullable: false },
+} as const;
+
+/**
+ * Plugin Runtime GitHub adapter.
+ * - Endpoint: `adapters/github.ts`
+ * - OAuth user tokens: define `github_oauth_users` when DatabaseHost is present
+ */
+export default definePlugin({
+  name: 'github',
+  metadata: {
+    displayName: 'GitHub Adapter',
+  },
+  setup(context) {
+    if (context.resources.has(databaseHostToken)) {
+      const host = context.resources.use(databaseHostToken);
+      defineGithubOauthUsersTable(host);
+      host.define('github_subscriptions', { ...GITHUB_SUBSCRIPTIONS_SCHEMA });
+    }
+
+    // Agent prompt contributor (orchestrator/deferred-worker GitHub guidance).
+    // `zhin.js/agent` is an optional peer — skip silently on IM-only installs.
+    let cancelled = false;
+    let unregister: (() => void) | undefined;
+    void Promise.all([
+      import('zhin.js/agent'),
+      import('./src/agent-prompt.js'),
+    ]).then(([agent, prompt]) => {
+      if (cancelled) return;
+      agent.registerAgentPromptContributor(prompt.createGithubAgentPromptContributor());
+      unregister = () => agent.unregisterAgentPromptContributor('github');
+    }).catch(() => { /* optional peer not installed */ });
+    return () => {
+      cancelled = true;
+      unregister?.();
+    };
+  },
+});

package/schema.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "host": {
+      "type": "string",
+      "description": "GitHub Enterprise hostname (default github.com)"
+    },
+    "webhook_path": {
+      "type": "string",
+      "default": "/github/webhook"
+    },
+    "webhookPath": {
+      "type": "string",
+      "default": "/github/webhook"
+    },
+    "poll_interval": {
+      "type": "number",
+      "default": 60,
+      "description": "Deferred: polling fallback was removed in the Plugin Runtime migration; currently parsed but unused"
+    },
+    "auto_reply_repos": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Repos whose Issue/PR comments auto-trigger AI without @bot"
+    },
+    "bot_login": {
+      "type": "string",
+      "description": "Override App bot login (default {slug}[bot])"
+    },
+    "workspace_root": {
+      "type": "string",
+      "description": "Managed git workspace root"
+    },
+    "endpoints": {
+      "type": "array",
+      "description": "多账号：一个插件实例挂多个 endpoint",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "GitHub App bot name"
+          },
+          "app_id": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "GitHub App ID"
+          },
+          "appId": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "GitHub App ID (camelCase alias)"
+          },
+          "private_key": {
+            "type": "string",
+            "description": "GitHub App private key (PEM content or file path)"
+          },
+          "privateKey": {
+            "type": "string",
+            "description": "GitHub App private key (camelCase alias)"
+          },
+          "webhook_secret": {
+            "type": "string",
+            "description": "Webhook HMAC secret; enables httpHostToken POST route"
+          },
+          "webhookSecret": {
+            "type": "string",
+            "description": "Webhook HMAC secret (camelCase alias)"
+          }
+        },
+        "required": [
+          "name"
+        ]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
+    }
+  },
+  "required": [
+    "endpoints"
+  ]
+}