@zhin.js/adapter-github 1.0.0 → 1.1.0

package/agent/tools/unbind.ts

@@ -0,0 +1,13 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { executeGithubUnbind } from '../../src/github-tool-handlers.js';
+
+export default defineAgentTool<{}>({
+  description: '解除你绑定的 GitHub 账号',
+  adapter: 'github',
+  inputSchema: z.object({}),
+  tags: ['github'],
+  async execute(input, context) {
+    return executeGithubUnbind({}, context.$client, context.message);
+  },
+});

package/agent/tools/unsubscribe.ts

@@ -0,0 +1,15 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { executeGithubUnsubscribe } from '../../src/github-tool-handlers.js';
+
+export default defineAgentTool<{ repo: string }>({
+  description: '取消订阅 GitHub 仓库的 Webhook 事件',
+  inputSchema: z.object({
+    repo: z.string().min(1),
+  }),
+  adapter: 'github',
+  tags: ['github'],
+  async execute(input, context) {
+    return executeGithubUnsubscribe(input, context.$client, context.message);
+  },
+});

package/agent/tools/whoami.ts

@@ -0,0 +1,13 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { executeGithubWhoami } from '../../src/github-tool-handlers.js';
+
+export default defineAgentTool<{}>({
+  description: '查看你绑定的 GitHub 账号信息',
+  adapter: 'github',
+  inputSchema: z.object({}),
+  tags: ['github'],
+  async execute(input, context) {
+    return executeGithubWhoami({}, context.$client, context.message);
+  },
+});

package/commands/endpoint/add/[id].js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { githubEndpointCommands } from "../../../lib/github-endpoint-commands.js";
+export default githubEndpointCommands.add;

package/commands/endpoint/add/[id].ts

@@ -0,0 +1,3 @@
+import { githubEndpointCommands } from '../../../src/github-endpoint-commands.js';
+
+export default githubEndpointCommands.add;

package/commands/endpoint/list.js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { githubEndpointCommands } from "../../lib/github-endpoint-commands.js";
+export default githubEndpointCommands.list;

package/commands/endpoint/list.ts

@@ -0,0 +1,3 @@
+import { githubEndpointCommands } from '../../src/github-endpoint-commands.js';
+
+export default githubEndpointCommands.list;

package/commands/endpoint/remove/[id].js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { githubEndpointCommands } from "../../../lib/github-endpoint-commands.js";
+export default githubEndpointCommands.remove;

package/commands/endpoint/remove/[id].ts

@@ -0,0 +1,3 @@
+import { githubEndpointCommands } from '../../../src/github-endpoint-commands.js';
+
+export default githubEndpointCommands.remove;

package/lib/client.d.ts

@@ -0,0 +1,36 @@
+import type { PluginDatabaseHost } from 'zhin.js';
+import { GhClient } from './gh-client.js';
+import type { ResolvedGithubConfig } from './protocol.js';
+import { WorkspaceManager } from './workspace-manager.js';
+/** GitHub SDK surface exposed to plugin handlers and Agent tools. */
+export declare class GithubClient {
+    #private;
+    readonly name: string;
+    readonly api: GhClient;
+    readonly config: ResolvedGithubConfig;
+    readonly database?: PluginDatabaseHost | undefined;
+    constructor(name: string, api: GhClient, config: ResolvedGithubConfig, database?: PluginDatabaseHost | undefined);
+    getUserOrDefaultApi(platform?: string, platformUid?: string): Promise<GhClient>;
+    get clientId(): string | null;
+    get host(): string | undefined;
+    get appSlug(): string | null;
+    get installations(): {
+        id: number;
+        account: {
+            login: string;
+            type: string;
+        };
+        target_type: string;
+    }[];
+    get workspaceManager(): WorkspaceManager;
+}
+export type GithubClientEventMap = Record<string, unknown>;
+declare module '@zhin.js/feature-kit' {
+    interface AdapterClientRegistry {
+        readonly github: {
+            readonly client: GithubClient;
+            readonly events: GithubClientEventMap;
+        };
+    }
+}
+export declare const githubClient: import("@zhin.js/adapter").EndpointClientToken<GithubClient, GithubClientEventMap>;

package/lib/client.js

@@ -0,0 +1,47 @@
+import path from 'node:path';
+import { defineEndpointClient } from 'zhin.js/adapter';
+import { lookupGithubOauthAccessToken } from './oauth-users.js';
+import { WorkspaceManager } from './workspace-manager.js';
+/** GitHub SDK surface exposed to plugin handlers and Agent tools. */
+export class GithubClient {
+    name;
+    api;
+    config;
+    database;
+    #workspaceManager;
+    constructor(name, api, config, database) {
+        this.name = name;
+        this.api = api;
+        this.config = config;
+        this.database = database;
+    }
+    async getUserOrDefaultApi(platform, platformUid) {
+        if (platform && platformUid) {
+            const token = await lookupGithubOauthAccessToken(this.database, platform, platformUid);
+            if (token)
+                return this.api.withToken(token);
+        }
+        return this.api;
+    }
+    get clientId() {
+        return this.api.clientId || null;
+    }
+    get host() {
+        return this.config.host;
+    }
+    get appSlug() {
+        return this.api.appSlug || null;
+    }
+    get installations() {
+        return this.api.installations || [];
+    }
+    get 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 const githubClient = defineEndpointClient('github');

package/lib/endpoint.d.ts

@@ -0,0 +1,36 @@
+import { Endpoint } from 'zhin.js/adapter';
+/**
+ * GithubEndpoint — lifecycle, outbound send, inbound admit.
+ */
+import { type EndpointSendRequest } from 'zhin.js/adapter';
+import type { HttpHost } from '@zhin.js/host-http';
+import type { CapabilityId, PluginDatabaseHost } from 'zhin.js';
+import { GhClient } from './gh-client.js';
+import { type GithubInboundComment, type ResolvedGithubConfig } from './protocol.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 declare class GithubEndpoint extends Endpoint<GithubClient> {
+    #private;
+    readonly client: GithubClient;
+    constructor(options: GithubEndpointOptions);
+    get config(): ResolvedGithubConfig;
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
+    /** Test / internal: admit a parsed comment when open. */
+    admit(comment: GithubInboundComment): void;
+    admitPlatform(name: string, event: unknown): void;
+}
+export declare function defaultCreateClient(config: ResolvedGithubConfig): GhClient;

package/lib/endpoint.js

@@ -0,0 +1,140 @@
+import { Endpoint } from 'zhin.js/adapter';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
+import { GhClient } from './gh-client.js';
+import { enrichInboundContent, formatInboundContent, formatOutboundBody, githubInboundConversation, parseChannelId, } from './protocol.js';
+import { registerGithubWebhookRoutes } from './webhook.js';
+import { GithubClient } from './client.js';
+/**
+ * GitHub 是代码协作面（issue/PR），无好友/群/频道等 IM 社交概念，
+ * 不适用 EndpointManagement 语义端口；本 endpoint 不暴露该端口。
+ */
+export class GithubEndpoint extends Endpoint {
+    #logger;
+    #options;
+    client;
+    #routeReleases = [];
+    #open = false;
+    #started = false;
+    constructor(options) {
+        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() {
+        return this.client.config;
+    }
+    async start() {
+        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() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    async stop() {
+        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 }) {
+        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) {
+        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, event) {
+        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) {
+    const appAuth = config.appId && config.privateKey
+        ? { appId: config.appId, privateKey: config.privateKey }
+        : undefined;
+    return new GhClient({ host: config.host, appAuth });
+}

package/lib/gh-client.d.ts

@@ -13,6 +13,17 @@ export interface AppAuth {
     /** PEM 格式私钥内容，或私钥文件路径 */
     privateKey: string;
 }
+export interface GitHubBotIdentity {
+    login: string;
+    email: string;
+    slug: string;
+    userId: number;
+}
+export interface GitHubCommitAuthor {
+    name: string;
+    email: string;
+    date?: string;
+}
 export interface GhClientOptions {
     /** GitHub Enterprise 主机名（默认 github.com） */
     host?: string;
@@ -153,6 +164,64 @@ export declare class GhClient {
         status: number;
         data: any;
     }>;
+    getFileContent(repo: string, path: string, ref?: string): Promise<{
+        ok: boolean;
+        status: number;
+        data: {
+            content: string;
+            sha: string;
+            encoding: string;
+        };
+    }>;
+    createOrUpdateFile(repo: string, path: string, content: string, message: string, options?: {
+        branch?: string;
+        sha?: string;
+    }): Promise<{
+        ok: boolean;
+        status: number;
+        data: {
+            commit: {
+                sha: string;
+                html_url?: string;
+            };
+            content: {
+                html_url?: string;
+            };
+        };
+    }>;
+    getRef(repo: string, ref: string): Promise<{
+        ok: boolean;
+        status: number;
+        data: {
+            ref: string;
+            object: {
+                sha: string;
+                type: string;
+            };
+        };
+    }>;
+    createRef(repo: string, ref: string, sha: string): Promise<{
+        ok: boolean;
+        status: number;
+        data: any;
+    }>;
+    createPullRequest(repo: string, title: string, head: string, base: string, body?: string): Promise<{
+        ok: boolean;
+        status: number;
+        data: {
+            number: number;
+            html_url: string;
+            head: {
+                ref: string;
+            };
+        };
+    }>;
+    getBotLogin(): string | null;
+    getCommitAuthor(): GitHubCommitAuthor | null;
+    getBotIdentitySync(): GitHubBotIdentity | null;
+    getBotIdentity(): Promise<GitHubBotIdentity | null>;
+    buildCloneUrl(repo: string, token: string): string;
+    resolveBotUserId(): Promise<number | null>;
     starRepo(repo: string): Promise<{
         ok: boolean;
         status: number;
@@ -193,6 +262,10 @@ export declare class GhClient {
     get appSlug(): string | null;
     /** App 的 client_id（verifyAuth 后从 /app 获取，用于 Device Flow） */
     private _clientId;
+    /** Bot 机器用户 numeric id（/users/{slug}[bot]） */
+    private _botUserId;
+    /** 确保 App 认证的 Installation Token 对指定 repo 有效，并返回 token */
+    ensureInstallationTokenForRepo(repo: string): Promise<string | undefined>;
     get clientId(): string | null;
     /**
      * 获取仓库事件（支持 ETag 条件请求）
@@ -225,4 +298,3 @@ export declare class GhClient {
         scope: string;
     } | null>;
 }
-//# sourceMappingURL=gh-client.d.ts.map

package/lib/gh-client.js

@@ -143,11 +143,12 @@ export class GhClient {
         }
         catch (err) {
             let data;
+            const errObj = err instanceof Error ? err : new Error(String(err));
             try {
-                data = err.stdout ? JSON.parse(err.stdout) : { message: err.message };
+                data = err.stdout ? JSON.parse(err.stdout) : { message: errObj.message };
             }
             catch {
-                data = { message: err.stderr?.trim() || err.message };
+                data = { message: err.stderr?.trim() || errObj.message };
             }
             return { ok: false, status: err.exitCode || 0, data };
         }
@@ -180,6 +181,7 @@ export class GhClient {
                     this._appSlug = appData.slug || null;
                     if (appData.client_id)
                         this._clientId = appData.client_id;
+                    await this.resolveBotUserId();
                     const repos = this._repoToInstallation.size;
                     return { ok: true, user: name, message: `GitHub App: ${name} (${this._allInstallations.length} 安装, ${repos} 仓库)` };
                 }
@@ -187,7 +189,7 @@ export class GhClient {
                 return { ok: false, user: '', message: `App Token 验证失败 (${appRes.status}): ${errBody}` };
             }
             catch (e) {
-                return { ok: false, user: '', message: e.message || 'App 认证失败' };
+                return { ok: false, user: '', message: (e instanceof Error ? e.message : String(e)) || 'App 认证失败' };
             }
         }
         // Token 模式（用户绑定）或 gh CLI 默认模式
@@ -208,7 +210,7 @@ export class GhClient {
             return { ok: true, user: login, message: `gh CLI: ${login}` };
         }
         catch (e) {
-            return { ok: false, user: '', message: e.message || 'gh 认证检查失败' };
+            return { ok: false, user: '', message: (e instanceof Error ? e.message : String(e)) || 'gh 认证检查失败' };
         }
     }
     // ── Issue 评论 (聊天核心) ─────────────────────────────────────────
@@ -264,6 +266,95 @@ export class GhClient {
     async deletePRReviewComment(repo, commentId) {
         return this.del(`/repos/${repo}/pulls/comments/${commentId}`);
     }
+    // ── Contents / Pulls（Bot 写操作）──────────────────────────────────
+    async getFileContent(repo, path, ref) {
+        let apiPath = `/repos/${repo}/contents/${path.split('/').map(encodeURIComponent).join('/')}`;
+        if (ref)
+            apiPath += `?ref=${encodeURIComponent(ref)}`;
+        return this.get(apiPath);
+    }
+    async createOrUpdateFile(repo, path, content, message, options) {
+        const body = {
+            message,
+            content: Buffer.from(content, 'utf-8').toString('base64'),
+        };
+        if (options?.branch)
+            body.branch = options.branch;
+        if (options?.sha)
+            body.sha = options.sha;
+        const apiPath = `/repos/${repo}/contents/${path.split('/').map(encodeURIComponent).join('/')}`;
+        return this.put(apiPath, body);
+    }
+    async getRef(repo, ref) {
+        return this.get(`/repos/${repo}/git/ref/${encodeURIComponent(ref)}`);
+    }
+    async createRef(repo, ref, sha) {
+        return this.post(`/repos/${repo}/git/refs`, { ref, sha });
+    }
+    async createPullRequest(repo, title, head, base, body) {
+        return this.post(`/repos/${repo}/pulls`, { title, head, base, body: body ?? '' });
+    }
+    getBotLogin() {
+        if (this._user)
+            return this._user;
+        if (this._appSlug)
+            return `${this._appSlug}[bot]`;
+        return null;
+    }
+    getCommitAuthor() {
+        const identity = this.getBotIdentitySync();
+        if (!identity)
+            return null;
+        return { name: identity.login, email: identity.email, date: new Date().toISOString() };
+    }
+    getBotIdentitySync() {
+        const slug = this._appSlug;
+        const login = this.getBotLogin();
+        if (!slug || !login || this._botUserId == null)
+            return null;
+        return {
+            login,
+            slug,
+            userId: this._botUserId,
+            email: `${this._botUserId}+${login}@users.noreply.github.com`,
+        };
+    }
+    async getBotIdentity() {
+        if (!this._appAuth)
+            return null;
+        if (this._botUserId == null)
+            await this.resolveBotUserId();
+        return this.getBotIdentitySync();
+    }
+    buildCloneUrl(repo, token) {
+        const host = this.host || 'github.com';
+        return `https://x-access-token:${encodeURIComponent(token)}@${host}/${repo}.git`;
+    }
+    async resolveBotUserId() {
+        if (this._botUserId != null)
+            return this._botUserId;
+        const slug = this._appSlug;
+        if (!slug)
+            return null;
+        const login = `${slug}[bot]`;
+        const baseUrl = this.host ? `https://${this.host}/api/v3` : 'https://api.github.com';
+        try {
+            const res = await fetch(`${baseUrl}/users/${encodeURIComponent(login)}`, {
+                headers: { Accept: 'application/vnd.github+json' },
+            });
+            if (!res.ok)
+                return null;
+            const data = (await res.json());
+            if (typeof data.id === 'number') {
+                this._botUserId = data.id;
+                return data.id;
+            }
+        }
+        catch {
+            return null;
+        }
+        return null;
+    }
     // ── Star ─────────────────────────────────────────────────────────
     async starRepo(repo) {
         return this.put(`/user/starred/${repo}`);
@@ -383,6 +474,15 @@ export class GhClient {
     get appSlug() { return this._appSlug; }
     /** App 的 client_id（verifyAuth 后从 /app 获取，用于 Device Flow） */
     _clientId = null;
+    /** Bot 机器用户 numeric id（/users/{slug}[bot]） */
+    _botUserId = null;
+    /** 确保 App 认证的 Installation Token 对指定 repo 有效，并返回 token */
+    async ensureInstallationTokenForRepo(repo) {
+        if (!this._appAuth)
+            return this.token;
+        await this.ensureTokenForRepo(repo);
+        return this.token;
+    }
     get clientId() { return this._clientId; }
     // ── 事件轮询 ─────────────────────────────────────────────────────
     /**
@@ -412,7 +512,8 @@ export class GhClient {
         }
         catch (err) {
             // 304 Not Modified — gh 会以非 0 退出码返回
-            if (err.stderr?.includes('304') || err.exitCode === 1) {
+            const ghErr = err instanceof Error ? err : null;
+            if (ghErr?.stderr?.includes('304') || ghErr?.exitCode === 1) {
                 return { events: [], etag: etag || null };
             }
             throw err;
@@ -441,7 +542,9 @@ export class GhClient {
             });
         }
         catch (e) {
-            throw new Error(`Device Flow 请求失败: 无法连接 ${baseUrl} (${e.cause?.code || e.message})。` +
+            const errMsg = e instanceof Error ? e.message : String(e);
+            const errCause = e instanceof Error ? e.cause?.code : undefined;
+            throw new Error(`Device Flow 请求失败: 无法连接 ${baseUrl} (${errCause || errMsg})。` +
                 `Device Flow 需要访问 github.com（非 api.github.com），请检查网络/代理设置。`);
         }
         if (!res.ok) {
@@ -491,4 +594,3 @@ export class GhClient {
         return null;
     }
 }
-//# sourceMappingURL=gh-client.js.map

package/lib/github-bot-handlers.d.ts

@@ -0,0 +1,27 @@
+/**
+ * GitHub App Bot workflow handlers (Installation Token identity).
+ */
+import type { Message } from 'zhin.js';
+import type { GithubClient } from './client.js';
+export declare function executeGithubPrepareWorkspace(args: {
+    repo?: string;
+}, client: GithubClient, commMessage?: Message): Promise<string>;
+export declare function executeGithubPatchFile(args: {
+    repo?: string;
+    path: string;
+    content: string;
+    message: string;
+    branch?: string;
+}, client: GithubClient, commMessage?: Message): Promise<string>;
+export declare function executeGithubPushBranch(args: {
+    repo?: string;
+    branch?: string;
+    message: string;
+}, client: GithubClient, commMessage?: Message): Promise<string>;
+export declare function executeGithubCreatePr(args: {
+    repo?: string;
+    title: string;
+    body?: string;
+    head?: string;
+    base?: string;
+}, client: GithubClient, commMessage?: Message): Promise<string>;