@zhin.js/adapter-github 1.0.1 → 1.1.2

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) {
+    return new GhClient({
+        host: config.host,
+        appAuth: { appId: config.appId, privateKey: config.privateKey },
+    });
+}

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

@@ -181,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} 仓库)` };
                 }
@@ -265,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}`);
@@ -384,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; }
     // ── 事件轮询 ─────────────────────────────────────────────────────
     /**
@@ -495,4 +594,3 @@ export class GhClient {
         return null;
     }
 }
-//# sourceMappingURL=gh-client.js.map

package/lib/github-channel-context.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Parse GitHub Issue/PR channel context from IM messages.
+ */
+import type { Message } from 'zhin.js';
+import { type ParsedChannel } from './types.js';
+import type { GhClient } from './gh-client.js';
+export interface GitHubChannelContext extends ParsedChannel {
+    channelId: string;
+}
+export declare function parseMessageChannel(message: Message): GitHubChannelContext | null;
+export declare function issueBranchName(number: number): string;
+export declare function resolveWorkspaceBranch(gh: GhClient, ctx: GitHubChannelContext): Promise<{
+    branch: string;
+    base: string;
+}>;
+export declare function formatChannelContext(ctx: GitHubChannelContext): string;

package/lib/github-channel-context.js

@@ -0,0 +1,31 @@
+import { buildChannelId, parseChannelId } from './types.js';
+export function parseMessageChannel(message) {
+    const channelId = message.$channel?.id;
+    if (!channelId)
+        return null;
+    const parsed = parseChannelId(channelId);
+    if (!parsed)
+        return null;
+    return { ...parsed, channelId };
+}
+export function issueBranchName(number) {
+    return `zhin/bot/issue-${number}`;
+}
+export async function resolveWorkspaceBranch(gh, ctx) {
+    if (ctx.type === 'pr') {
+        const pr = await gh.getPR(ctx.repo, ctx.number);
+        if (pr.ok && pr.data?.head?.ref) {
+            const base = pr.data.base?.ref ?? 'main';
+            return { branch: pr.data.head.ref, base };
+        }
+        throw new Error(`无法读取 PR #${ctx.number} 的 head 分支`);
+    }
+    const repoInfo = await gh.getRepo(ctx.repo);
+    const base = repoInfo.ok && repoInfo.data?.default_branch
+        ? String(repoInfo.data.default_branch)
+        : 'main';
+    return { branch: issueBranchName(ctx.number), base };
+}
+export function formatChannelContext(ctx) {
+    return buildChannelId(ctx.repo, ctx.type, ctx.number);
+}

package/lib/github-runtime-state.d.ts

@@ -0,0 +1 @@
+export declare const githubRuntimeStateToken: import("zhin.js").Token<import("@zhin.js/adapter").EndpointRuntimeState>;

package/lib/github-runtime-state.js

@@ -0,0 +1,6 @@
+/**
+ * GitHub 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
+ * 由 plugin.ts setup() provide，adapter create 与 `github endpoint` 命令共享（同一 owner generation）。
+ */
+import { defineEndpointRuntimeStateToken } from 'zhin.js/adapter';
+export const githubRuntimeStateToken = defineEndpointRuntimeStateToken('github');

package/lib/index.d.ts

@@ -1,34 +1,9 @@
-import { GitHubAdapter } from './adapter.js';
-declare module 'zhin.js' {
-    interface Adapters {
-        github: GitHubAdapter;
-    }
-    namespace Plugin {
-        interface Contexts {
-            router: import('@zhin.js/host-router').Router;
-        }
-    }
-    interface Models {
-        github_subscriptions: {
-            id: number;
-            repo: string;
-            events: import('./types.js').EventType[];
-            target_id: string;
-            target_type: 'private' | 'group' | 'channel';
-            adapter: string;
-            endpoint: string;
-        };
-        github_events: {
-            id: number;
-            repo: string;
-            event_type: string;
-            payload: any;
-        };
-        github_oauth_users: import('./types.js').GitHubOAuthUser;
-    }
-}
+export { buildChannelId, enrichInboundContent, formatInboundContent, formatNotification, formatOutboundBody, normalizeWebhookPath, parseChannelId, parseIssueCommentInbound, parsePrReviewCommentInbound, parsePrReviewInbound, resolveGithubConfig, shouldAutoReplyRepo, verifyWebhookSignature, type GithubEndpointConfig, type GithubInboundComment, type GithubWireSegment, type ResolvedGithubConfig, } from './protocol.js';
 export * from './types.js';
-export { GitHubEndpoint, parseMarkdown, toMarkdown } from './endpoint.js';
-export { GitHubAdapter } from './adapter.js';
 export { GhClient } from './gh-client.js';
-//# sourceMappingURL=index.d.ts.map
+export { GithubClient, githubClient, type GithubClientEventMap } from './client.js';
+export { WorkspaceManager } from './workspace-manager.js';
+export { parseMessageChannel, issueBranchName, resolveWorkspaceBranch, formatChannelContext, } from './github-channel-context.js';
+export { GithubEndpoint, defaultCreateClient, type GithubEndpointOptions, } from './endpoint.js';
+export { GITHUB_OAUTH_USERS_TABLE, GITHUB_OAUTH_USERS_SCHEMA, defineGithubOauthUsersTable, lookupGithubOauthAccessToken, } from './oauth-users.js';
+export { registerGithubWebhookRoutes, handleGithubWebhookRequest, dispatchGithubWebhookPayload, type GithubWebhookHandler, } from './webhook.js';