@zhin.js/adapter-github 1.0.0 → 1.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhin.js/adapter-github",
-  "version": "1.0.0",
-  "description": "Zhin.js adapter for GitHub (gh CLI) — treat issues/PRs as chat channels, full repo management, webhook notifications",
+  "version": "1.1.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",
-    "client",
-    "dist",
-    "skills",
-    "plugin.yml",
-    "README.md"
-  ],
   "keywords": [
     "zhin",
     "zhin.js",
@@ -44,30 +35,94 @@
     "url": "https://github.com/lc-cn"
   },
   "license": "MIT",
-  "devDependencies": {
-    "typescript": "^6.0.3",
-    "zhin.js": "2.0.0"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhinjs/zhin.git",
+    "directory": "plugins/adapters/github"
+  },
+  "dependencies": {
+    "@zhin.js/adapter": "1.1.12",
+    "@zhin.js/core": "1.1.35",
+    "@zhin.js/feature-kit": "1.1.0",
+    "@zhin.js/host-http": "1.1.0",
+    "@zhin.js/im-contract": "1.1.0",
+    "@zhin.js/logger": "1.1.0"
   },
   "peerDependencies": {
-    "@zhin.js/host-router": "1.0.0",
-    "zhin.js": "2.0.0"
+    "zod": "^4.0.0",
+    "@zhin.js/adapter": "^1.1.12",
+    "@zhin.js/agent": "^1.1.23",
+    "@zhin.js/command": "^1.1.0",
+    "@zhin.js/core": "^1.1.35",
+    "@zhin.js/host-http": "^1.1.0",
+    "@zhin.js/prompt-section": "^1.1.0",
+    "zhin.js": "^1.1.0"
   },
   "peerDependenciesMeta": {
-    "@zhin.js/host-router": {
+    "@zhin.js/agent": {
+      "optional": true
+    },
+    "@zhin.js/command": {
+      "optional": true
+    },
+    "@zhin.js/prompt-section": {
+      "optional": true
+    },
+    "zhin.js": {
+      "optional": true
+    },
+    "zod": {
       "optional": true
     }
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/zhinjs/zhin.git",
-    "directory": "plugins/adapters/github"
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10",
+    "zod": "^4.4.3",
+    "@zhin.js/agent": "1.1.23",
+    "@zhin.js/prompt-section": "1.1.0",
+    "zhin.js": "1.1.0"
   },
+  "files": [
+    "adapters",
+    "commands",
+    "plugin.js",
+    "schema.json",
+    "src",
+    "lib",
+    "agent",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "zhin": {
+    "protocol": 1,
+    "type": "plugin",
+    "entry": "./plugin.js",
+    "engine": "^1.0.0",
+    "runtime": "trusted",
+    "features": [
+      {
+        "package": "@zhin.js/adapter",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/command",
+        "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.js

@@ -0,0 +1,38 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { createEndpointRuntimeState } from 'zhin.js/adapter';
+import { definePlugin, databaseHostToken } from 'zhin.js';
+import { githubRuntimeStateToken } from "./lib/github-runtime-state.js";
+import { defineGithubOauthUsersTable } from "./lib/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 },
+};
+/**
+ * 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) {
+        // 运行中 endpoint 注册表（github.endpoint list 的"运行中"数据源）
+        context.resources.provide(githubRuntimeStateToken, createEndpointRuntimeState());
+        if (context.resources.has(databaseHostToken)) {
+            const host = context.resources.use(databaseHostToken);
+            defineGithubOauthUsersTable(host);
+            host.define('github_subscriptions', { ...GITHUB_SUBSCRIPTIONS_SCHEMA });
+        }
+    },
+});

package/schema.json

@@ -0,0 +1,130 @@
+{
+  "$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"
+    },
+    "master": {
+      "type": [
+        "string",
+        "number"
+      ],
+      "description": "框架 master（GitHub user login or id；AI/工具权限、endpoint 管理）。endpoints[i].master 可逐项覆盖"
+    },
+    "trusted": {
+      "type": "array",
+      "items": {
+        "type": [
+          "string",
+          "number"
+        ],
+        "description": "Trusted GitHub user login or id"
+      },
+      "description": "框架 trusted 用户列表（弱于 master）。endpoints[i].trusted 可逐项追加"
+    },
+    "endpoints": {
+      "type": "array",
+      "description": "多账号：一个插件实例挂多个 endpoint",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "master": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "本 endpoint 的框架 master（GitHub user login or id）；覆盖顶层 master"
+          },
+          "trusted": {
+            "type": "array",
+            "items": {
+              "type": [
+                "string",
+                "number"
+              ],
+              "description": "Trusted GitHub user login or id"
+            },
+            "description": "本 endpoint 的 trusted 列表"
+          },
+          "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)"
+          },
+          "id": {
+            "type": "string",
+            "description": "GitHub App bot name"
+          }
+        },
+        "required": [
+          "id"
+        ]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
+    }
+  },
+  "required": [
+    "endpoints"
+  ]
+}

package/src/client.ts

@@ -0,0 +1,65 @@
+import path from 'node:path';
+import type { PluginDatabaseHost } from 'zhin.js';
+import { defineEndpointClient } from 'zhin.js/adapter';
+import { GhClient } from './gh-client.js';
+import { lookupGithubOauthAccessToken } from './oauth-users.js';
+import type { ResolvedGithubConfig } from './protocol.js';
+import { WorkspaceManager } from './workspace-manager.js';
+
+/** GitHub SDK surface exposed to plugin handlers and Agent tools. */
+export class GithubClient {
+  #workspaceManager?: WorkspaceManager;
+
+  constructor(
+    readonly name: string,
+    readonly api: GhClient,
+    readonly config: ResolvedGithubConfig,
+    readonly database?: PluginDatabaseHost,
+  ) {}
+
+  async getUserOrDefaultApi(platform?: string, platformUid?: string): Promise<GhClient> {
+    if (platform && platformUid) {
+      const token = await lookupGithubOauthAccessToken(this.database, platform, platformUid);
+      if (token) return this.api.withToken(token);
+    }
+    return this.api;
+  }
+
+  get clientId(): string | null {
+    return this.api.clientId || null;
+  }
+
+  get host(): string | undefined {
+    return this.config.host;
+  }
+
+  get appSlug(): string | null {
+    return this.api.appSlug || null;
+  }
+
+  get installations() {
+    return this.api.installations || [];
+  }
+
+  get workspaceManager(): WorkspaceManager {
+    if (!this.#workspaceManager) {
+      const root = this.config.workspaceRoot
+        ?? path.join(process.cwd(), 'data', 'github-workspaces');
+      this.#workspaceManager = new WorkspaceManager(this.api, root);
+    }
+    return this.#workspaceManager;
+  }
+}
+
+export type GithubClientEventMap = Record<string, unknown>;
+
+declare module '@zhin.js/feature-kit' {
+  interface AdapterClientRegistry {
+    readonly github: {
+      readonly client: GithubClient;
+      readonly events: GithubClientEventMap;
+    };
+  }
+}
+
+export const githubClient = defineEndpointClient<GithubClient, GithubClientEventMap>('github');

package/src/endpoint.ts

@@ -0,0 +1,169 @@
+import { Endpoint } from 'zhin.js/adapter';
+/**
+ * GithubEndpoint — lifecycle, outbound send, inbound admit.
+ */
+import { type EndpointSendRequest } from 'zhin.js/adapter';
+import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
+import type { CapabilityId, PluginDatabaseHost } from 'zhin.js';
+import { GhClient } from './gh-client.js';
+import {
+  enrichInboundContent,
+  formatInboundContent,
+  formatOutboundBody,
+  githubInboundConversation,
+  parseChannelId,
+  type GithubInboundComment,
+  type ResolvedGithubConfig,
+} from './protocol.js';
+import { registerGithubWebhookRoutes } from './webhook.js';
+import { GithubClient } from './client.js';
+
+export interface GithubEndpointOptions {
+  readonly id: CapabilityId;
+  readonly http?: HttpHost;
+  readonly database?: PluginDatabaseHost;
+  readonly config: ResolvedGithubConfig;
+  readonly createClient?: (config: ResolvedGithubConfig) => GhClient;
+}
+
+/**
+ * GitHub 是代码协作面（issue/PR），无好友/群/频道等 IM 社交概念，
+ * 不适用 EndpointManagement 语义端口；本 endpoint 不暴露该端口。
+ */
+export class GithubEndpoint extends Endpoint<GithubClient> {
+  readonly #logger!: ReturnType<typeof getAdapterLogger>;
+
+  readonly #options: GithubEndpointOptions;
+  readonly client: GithubClient;
+  #routeReleases: HttpRouteRegistration[] = [];
+  #open = false;
+  #started = false;
+
+  constructor(options: GithubEndpointOptions) {
+    super();
+    this.#logger = getAdapterLogger('github', options.config.id);
+    this.#options = options;
+    const api = options.createClient?.(options.config) ?? defaultCreateClient(options.config);
+    this.client = new GithubClient(options.config.id, api, options.config, options.database);
+  }
+
+  get config(): ResolvedGithubConfig {
+    return this.client.config;
+  }
+
+  async start(): Promise<void> {
+    if (this.#started) return;
+    this.#started = true;
+    try {
+      const result = await this.client.api.verifyAuth();
+      if (!result.ok) throw new Error(`GitHub 认证失败: ${result.message}`);
+      if (this.client.config.webhookSecret) {
+        if (!this.#options.http) {
+          throw new TypeError('GitHub webhook_secret requires httpHostToken');
+        }
+        this.#routeReleases.push(...registerGithubWebhookRoutes(this.#options.http, this));
+        this.#logger.debug(formatCompact({
+          endpoint: this.client.name,
+          op: 'webhook',
+          path: this.client.config.webhookPath,
+        }));
+      } else {
+        this.#logger.debug(formatCompact({
+          endpoint: this.client.name,
+          op: 'connect',
+          mode: 'api-only',
+          bot: this.client.api.authenticatedUser,
+        }));
+      }
+    } catch (error) {
+      await this.stop();
+      this.#logger.error('Failed to connect GitHub endpoint:', error);
+      throw error;
+    }
+  }
+
+  open(): void {
+    this.#open = true;
+  }
+
+  close(): void {
+    this.#open = false;
+  }
+
+  async stop(): Promise<void> {
+    this.#open = false;
+    for (const release of this.#routeReleases.splice(0)) release();
+    this.#started = false;
+    this.#logger.debug(formatCompact({ op: 'disconnect' }));
+  }
+
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
+    const parsed = parseChannelId(conversation.id);
+    if (!parsed) throw new Error(`无效的 GitHub conversation ID: ${conversation.id}`);
+    const text = formatOutboundBody(payload);
+    const r = parsed.type === 'issue'
+      ? await this.client.api.createIssueComment(parsed.repo, parsed.number, text)
+      : await this.client.api.createPRComment(parsed.repo, parsed.number, text);
+    if (!r.ok) throw new Error(`发送失败: ${JSON.stringify(r.data)}`);
+    this.#logger.debug(formatCompact({
+      op: 'github_send',
+      endpoint: this.client.name,
+      target: `${conversation.kind}:${conversation.id}`,
+      messageId: r.data.id,
+    }));
+    return String(r.data.id);
+  }
+
+  /** Test / internal: admit a parsed comment when open. */
+  admit(comment: GithubInboundComment): void {
+    if (!this.#open) return;
+    const botUser = this.client.config.botLogin
+      || this.client.api.getBotLogin()
+      || this.client.api.authenticatedUser;
+    if (botUser && comment.sender === botUser) return;
+    const conversation = githubInboundConversation(String(this.#options.id), comment);
+    const content = enrichInboundContent(
+      formatInboundContent(comment.content),
+      this.client.config,
+      botUser ?? undefined,
+      comment.repo,
+    );
+    void this.emit('message.receive', {
+      conversation,
+      message: { conversation, id: comment.id },
+      content,
+      sender: { id: comment.sender, name: comment.sender },
+      endpointId: this.client.name,
+      metadata: Object.freeze({
+        repo: comment.repo,
+        kind: comment.kind,
+        createdAt: comment.createdAt,
+      }),
+    }).catch((err) => {
+      this.#logger.warn(formatCompact({
+        op: 'github_gateway_receive_failed',
+        target: `${conversation.kind}:${conversation.id}`,
+        error: err instanceof Error ? err.message : String(err),
+      }));
+    });
+  }
+
+  admitPlatform(name: string, event: unknown): void {
+    if (!this.#open) return;
+    void this.emitPlatform(name, event).catch((error) => {
+      this.#logger.warn(formatCompact({
+        op: 'github_platform_event_failed',
+        event: name,
+        error: error instanceof Error ? error.message : String(error),
+      }));
+    });
+  }
+}
+
+export function defaultCreateClient(config: ResolvedGithubConfig): GhClient {
+  const appAuth = config.appId && config.privateKey
+    ? { appId: config.appId, privateKey: config.privateKey }
+    : undefined;
+  return new GhClient({ host: config.host, appAuth });
+}