@zhin.js/adapter-github 1.0.1 → 1.1.0

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

@@ -1,26 +1,36 @@
+import { Endpoint } from 'zhin.js/adapter';
 /**
- * GitHub Endpoint 实现（基于 gh CLI）
+ * GithubEndpoint — lifecycle, outbound send, inbound admit.
  */
-import { Endpoint, Message, SendContent, SendOptions, type MessageSegment } from 'zhin.js';
-import type { GitHubEndpointConfig, IssueCommentPayload, PRReviewCommentPayload, PRReviewPayload } from './types.js';
-import type { GitHubAdapter } from './adapter.js';
+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';
-export declare function parseMarkdown(md: string): MessageSegment[];
-export declare function toMarkdown(content: SendContent): string;
-export declare class GitHubEndpoint implements Endpoint<GitHubEndpointConfig, IssueCommentPayload> {
-    adapter: GitHubAdapter;
-    $config: GitHubEndpointConfig;
-    $connected: boolean;
-    gh: GhClient;
-    get $id(): string;
-    get logger(): import("zhin.js").Logger;
-    constructor(adapter: GitHubAdapter, $config: GitHubEndpointConfig);
-    $connect(): Promise<void>;
-    $disconnect(): Promise<void>;
-    $formatMessage(payload: IssueCommentPayload): Message<IssueCommentPayload>;
-    formatPRReviewComment(payload: PRReviewCommentPayload): Message<PRReviewCommentPayload>;
-    formatPRReview(payload: PRReviewPayload): Message<PRReviewPayload> | null;
-    $sendMessage(options: SendOptions): Promise<string>;
-    $recallMessage(id: string): Promise<void>;
+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;
 }
-//# sourceMappingURL=endpoint.d.ts.map
+/**
+ * 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

@@ -1,160 +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 Endpoint 实现（基于 gh CLI）
+ * GitHub 是代码协作面（issue/PR），无好友/群/频道等 IM 社交概念，
+ * 不适用 EndpointManagement 语义端口；本 endpoint 不暴露该端口。
  */
-import { formatCompact, Message } from 'zhin.js';
-import { buildChannelId, parseChannelId } from './types.js';
-import { GhClient } from './gh-client.js';
-export function parseMarkdown(md) {
-    const segments = [];
-    const mentionRe = /@(\w[-\w]*)/g;
-    let lastIdx = 0;
-    let match;
-    while ((match = mentionRe.exec(md)) !== null) {
-        if (match.index > lastIdx)
-            segments.push({ type: 'text', data: { text: md.slice(lastIdx, match.index) } });
-        segments.push({ type: 'at', data: { id: match[1], name: match[1], text: match[0] } });
-        lastIdx = match.index + match[0].length;
-    }
-    if (lastIdx < md.length)
-        segments.push({ type: 'text', data: { text: md.slice(lastIdx) } });
-    return segments.length ? segments : [{ type: 'text', data: { text: md } }];
-}
-export function toMarkdown(content) {
-    if (!Array.isArray(content))
-        content = [content];
-    return content.map(seg => {
-        if (typeof seg === 'string')
-            return seg;
-        switch (seg.type) {
-            case 'text': return seg.data.text || '';
-            case 'at': return `@${seg.data.name || seg.data.id}`;
-            case 'image': return seg.data.url ? `![image](${seg.data.url})` : '[image]';
-            case 'link': return `[${seg.data.text || seg.data.url}](${seg.data.url})`;
-            default: return seg.data?.text || `[${seg.type}]`;
-        }
-    }).join('');
-}
-export class GitHubEndpoint {
-    adapter;
-    $config;
-    $connected = false;
-    gh;
-    get $id() { return this.$config.name; }
-    get logger() {
-        return this.adapter.plugin.logger;
+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);
     }
-    constructor(adapter, $config) {
-        this.adapter = adapter;
-        this.$config = $config;
-        const { host, app_id, private_key } = $config;
-        const appAuth = app_id && private_key
-            ? { appId: app_id, privateKey: private_key }
-            : undefined;
-        this.gh = new GhClient({ host, appAuth });
+    get config() {
+        return this.client.config;
     }
-    async $connect() {
-        const result = await this.gh.verifyAuth();
-        if (!result.ok)
-            throw new Error(`GitHub 认证失败: ${result.message}`);
-        this.$connected = true;
-        this.logger.info(formatCompact({ endpoint: this.$id }));
-    }
-    async $disconnect() {
-        this.$connected = false;
-        this.logger.debug(formatCompact({ endpoint: this.$id, disconnect: true }));
+    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;
+        }
     }
-    $formatMessage(payload) {
-        const repo = payload.repository.full_name;
-        const number = payload.issue.number;
-        const isPR = 'pull_request' in payload.issue;
-        const channelId = buildChannelId(repo, isPR ? 'pr' : 'issue', number);
-        const gh = this.gh;
-        const result = Message.from(payload, {
-            $id: payload.comment.id.toString(),
-            $adapter: 'github',
-            $endpoint: this.$config.name,
-            $sender: { id: payload.sender.login, name: payload.sender.login },
-            $channel: { id: channelId, type: 'group' },
-            $content: parseMarkdown(payload.comment.body),
-            $raw: payload.comment.body,
-            $timestamp: new Date(payload.comment.created_at).getTime(),
-            $recall: async () => { await gh.deleteIssueComment(repo, payload.comment.id); },
-            $reply: async (content, quote) => {
-                const text = toMarkdown(content);
-                const finalBody = quote ? `> ${payload.comment.body.split('\n')[0]}\n\n${text}` : text;
-                const r = await gh.createIssueComment(repo, number, finalBody);
-                return r.ok ? r.data.id.toString() : '';
-            },
-        });
-        return result;
+    open() {
+        this.#open = true;
     }
-    formatPRReviewComment(payload) {
-        const repo = payload.repository.full_name;
-        const number = payload.pull_request.number;
-        const channelId = buildChannelId(repo, 'pr', number);
-        const gh = this.gh;
-        const body = payload.comment.path
-            ? `**${payload.comment.path}**\n${payload.comment.diff_hunk ? '```diff\n' + payload.comment.diff_hunk + '\n```\n' : ''}${payload.comment.body}`
-            : payload.comment.body;
-        return Message.from(payload, {
-            $id: payload.comment.id.toString(),
-            $adapter: 'github',
-            $endpoint: this.$config.name,
-            $sender: { id: payload.sender.login, name: payload.sender.login },
-            $channel: { id: channelId, type: 'group' },
-            $content: parseMarkdown(body),
-            $raw: body,
-            $timestamp: new Date(payload.comment.created_at).getTime(),
-            $recall: async () => { await gh.deletePRReviewComment(repo, payload.comment.id); },
-            $reply: async (content) => {
-                const r = await gh.createPRComment(repo, number, toMarkdown(content));
-                return r.ok ? r.data.id.toString() : '';
-            },
-        });
+    close() {
+        this.#open = false;
     }
-    formatPRReview(payload) {
-        if (!payload.review.body)
-            return null;
-        const repo = payload.repository.full_name;
-        const number = payload.pull_request.number;
-        const channelId = buildChannelId(repo, 'pr', number);
-        const gh = this.gh;
-        const stateLabel = {
-            approved: '✅ APPROVED', changes_requested: '🔄 CHANGES REQUESTED',
-            commented: '💬 COMMENTED', dismissed: '❌ DISMISSED',
-        };
-        const body = `**[${stateLabel[payload.review.state] || payload.review.state}]**\n${payload.review.body}`;
-        return Message.from(payload, {
-            $id: payload.review.id.toString(),
-            $adapter: 'github',
-            $endpoint: this.$config.name,
-            $sender: { id: payload.sender.login, name: payload.sender.login },
-            $channel: { id: channelId, type: 'group' },
-            $content: parseMarkdown(body),
-            $raw: body,
-            $timestamp: new Date(payload.review.submitted_at).getTime(),
-            $recall: async () => { },
-            $reply: async (content) => {
-                const r = await gh.createPRComment(repo, number, toMarkdown(content));
-                return r.ok ? r.data.id.toString() : '';
-            },
-        });
+    async stop() {
+        this.#open = false;
+        for (const release of this.#routeReleases.splice(0))
+            release();
+        this.#started = false;
+        this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
-    async $sendMessage(options) {
-        const parsed = parseChannelId(options.id);
+    async send({ conversation, payload }) {
+        const parsed = parseChannelId(conversation.id);
         if (!parsed)
-            throw new Error(`无效的 GitHub channel ID: ${options.id}`);
-        const text = toMarkdown(options.content);
+            throw new Error(`无效的 GitHub conversation ID: ${conversation.id}`);
+        const text = formatOutboundBody(payload);
         const r = parsed.type === 'issue'
-            ? await this.gh.createIssueComment(parsed.repo, parsed.number, text)
-            : await this.gh.createPRComment(parsed.repo, parsed.number, text);
+            ? 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(`${this.$id} send → ${options.id}: ${text.slice(0, 80)}...`);
-        return r.data.id.toString();
+        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);
     }
-    async $recallMessage(id) {
-        this.logger.warn(formatCompact({ op: 'recall', ok: false, error: 'use message.$recall()' }));
+    /** 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),
+            }));
+        });
     }
 }
-//# sourceMappingURL=endpoint.js.map
+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