@zhin.js/adapter-github 3.0.2 → 4.0.0

package/lib/endpoint.js

@@ -0,0 +1,165 @@
+/**
+ * GithubEndpoint — lifecycle, outbound send, inbound admit.
+ */
+import path from 'node:path';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { GhClient } from './gh-client.js';
+import { registerGithubAgentEndpoint } from './github-agent-deps.js';
+import { lookupGithubOauthAccessToken } from './oauth-users.js';
+import { enrichInboundContent, formatInboundContent, formatOutboundBody, parseChannelId, } from './protocol.js';
+import { registerGithubWebhookRoutes } from './webhook.js';
+import { WorkspaceManager } from './workspace-manager.js';
+const logger = getLogger('github');
+export class GithubEndpoint {
+    #options;
+    gh;
+    config;
+    name;
+    #workspaceManager = null;
+    #routeReleases = [];
+    #open = false;
+    #started = false;
+    #unregisterAgent;
+    constructor(options) {
+        this.#options = options;
+        this.config = options.config;
+        this.name = options.config.name;
+        this.gh = options.createClient?.(options.config) ?? defaultCreateClient(options.config);
+    }
+    getAPI() {
+        return this.gh;
+    }
+    async getUserOrDefaultAPI(platform, platformUid) {
+        if (platform && platformUid) {
+            const token = await lookupGithubOauthAccessToken(this.#options.database, platform, platformUid);
+            if (token)
+                return this.gh.withToken(token);
+        }
+        return this.gh;
+    }
+    getClientId() {
+        return this.gh.clientId || null;
+    }
+    getHost() {
+        return this.config.host;
+    }
+    getAppSlug() {
+        return this.gh.appSlug || null;
+    }
+    getInstallations() {
+        return this.gh.installations || [];
+    }
+    getWorkspaceManager() {
+        if (this.#workspaceManager)
+            return this.#workspaceManager;
+        const workspaceRoot = this.config.workspaceRoot
+            ?? path.join(process.cwd(), 'data', 'github-workspaces');
+        this.#workspaceManager = new WorkspaceManager(this.gh, workspaceRoot);
+        return this.#workspaceManager;
+    }
+    getDatabase() {
+        return this.#options.database;
+    }
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        try {
+            const result = await this.gh.verifyAuth();
+            if (!result.ok)
+                throw new Error(`GitHub 认证失败: ${result.message}`);
+            this.#unregisterAgent = registerGithubAgentEndpoint(this.name, this);
+            if (this.config.webhookSecret) {
+                if (!this.#options.http) {
+                    throw new TypeError('GitHub webhook_secret requires httpHostToken');
+                }
+                this.#routeReleases.push(...registerGithubWebhookRoutes(this.#options.http, this));
+                logger.debug(formatCompact({
+                    endpoint: this.name,
+                    op: 'webhook',
+                    path: this.config.webhookPath,
+                }));
+            }
+            else {
+                logger.debug(formatCompact({
+                    endpoint: this.name,
+                    op: 'connect',
+                    mode: 'api-only',
+                    bot: this.gh.authenticatedUser,
+                }));
+            }
+        }
+        catch (error) {
+            await this.stop();
+            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.#unregisterAgent?.();
+        this.#unregisterAgent = undefined;
+        this.#started = false;
+        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.name }));
+    }
+    async send({ target, payload }) {
+        const parsed = parseChannelId(target);
+        if (!parsed)
+            throw new Error(`无效的 GitHub channel ID: ${target}`);
+        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);
+        if (!r.ok)
+            throw new Error(`发送失败: ${JSON.stringify(r.data)}`);
+        logger.debug(formatCompact({
+            op: 'github_send',
+            endpoint: this.name,
+            target,
+            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.config.botLogin || this.gh.getBotLogin() || this.gh.authenticatedUser;
+        if (botUser && comment.sender === botUser)
+            return;
+        const content = enrichInboundContent(formatInboundContent(comment.content), this.config, botUser ?? undefined, comment.repo);
+        void this.#options.gateway.receive({
+            adapter: this.#options.id,
+            target: comment.channelId,
+            content,
+            sender: comment.sender,
+            id: comment.id,
+            metadata: Object.freeze({
+                endpoint: this.name,
+                repo: comment.repo,
+                kind: comment.kind,
+                createdAt: comment.createdAt,
+            }),
+        }).catch((err) => {
+            logger.warn(formatCompact({
+                op: 'github_gateway_receive_failed',
+                target: comment.channelId,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+}
+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

@@ -0,0 +1,300 @@
+/**
+ * GitHub CLI (`gh`) 客户端封装
+ *
+ * 支持三种认证方式：
+ * 1. gh CLI 默认凭据（gh auth login）
+ * 2. GitHub App — JWT → Installation Token（自动续期）
+ * 3. 个人 OAuth Token（用户绑定 / Device Flow）
+ *
+ * 零外部依赖，使用 Node.js 原生模块。
+ */
+export interface AppAuth {
+    appId: string | number;
+    /** 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;
+    /** 覆盖 gh CLI 默认认证的 Personal Access Token / OAuth Token */
+    token?: string;
+    /** GitHub App 认证 — 自动管理 Installation Token */
+    appAuth?: AppAuth;
+}
+export declare class GhClient {
+    private host?;
+    private token?;
+    private _appAuth?;
+    private _resolvedKey?;
+    private _user;
+    /** Installation Token 缓存: installationId → { token, expiresAt } */
+    private _installationTokens;
+    /** repo(小写) → installationId */
+    private _repoToInstallation;
+    /** 所有 Installation 信息 */
+    private _allInstallations;
+    /** 上次 syncInstallations 时间 (ms) */
+    private _lastSyncTime;
+    constructor(options?: GhClientOptions);
+    /** 创建使用指定 token 的副本（共享 host 配置，不继承 App 认证） */
+    withToken(token: string): GhClient;
+    get authenticatedUser(): string | null;
+    private exec;
+    /**
+     * 确保 App 认证的 Installation Token 有效（自动按 repo 查找对应安装）
+     * @param repo 仓库全名（owner/repo），用于选择正确的 Installation
+     */
+    private ensureTokenForRepo;
+    request<T = any>(method: string, path: string, body?: any, headers?: Record<string, string>): Promise<{
+        ok: boolean;
+        status: number;
+        data: T;
+    }>;
+    private get;
+    private post;
+    private patch;
+    private put;
+    private del;
+    verifyAuth(): Promise<{
+        ok: boolean;
+        user: string;
+        message: string;
+    }>;
+    getRepo(repo: string): Promise<{
+        ok: boolean;
+        status: number;
+        data: any;
+    }>;
+    listIssues(repo: string, state?: 'open' | 'closed' | 'all'): Promise<{
+        ok: boolean;
+        status: number;
+        data: any[];
+    }>;
+    getIssue(repo: string, number: number): Promise<{
+        ok: boolean;
+        status: number;
+        data: any;
+    }>;
+    listPRs(repo: string, state?: 'open' | 'closed' | 'all'): Promise<{
+        ok: boolean;
+        status: number;
+        data: any[];
+    }>;
+    getPR(repo: string, number: number): Promise<{
+        ok: boolean;
+        status: number;
+        data: any;
+    }>;
+    searchRepos(query: string, perPage?: number): Promise<{
+        ok: boolean;
+        status: number;
+        data: {
+            total_count: number;
+            items: any[];
+        };
+    }>;
+    listCommits(repo: string, sha?: string, _path?: string, perPage?: number): Promise<{
+        ok: boolean;
+        status: number;
+        data: any[];
+    }>;
+    listBranches(repo: string, perPage?: number): Promise<{
+        ok: boolean;
+        status: number;
+        data: any[];
+    }>;
+    listReleases(repo: string, perPage?: number): Promise<{
+        ok: boolean;
+        status: number;
+        data: any[];
+    }>;
+    listWorkflowRuns(repo: string, perPage?: number): Promise<{
+        ok: boolean;
+        status: number;
+        data: {
+            workflow_runs: any[];
+        };
+    }>;
+    closeIssue(repo: string, number: number): Promise<{
+        ok: boolean;
+        status: number;
+        data: any;
+    }>;
+    closePR(repo: string, number: number): Promise<{
+        ok: boolean;
+        status: number;
+        data: any;
+    }>;
+    createIssueComment(repo: string, issueNumber: number, body: string): Promise<{
+        ok: boolean;
+        status: number;
+        data: {
+            id: number;
+            html_url: string;
+            message?: string;
+        };
+    }>;
+    deleteIssueComment(repo: string, commentId: number): Promise<{
+        ok: boolean;
+        status: number;
+        data: any;
+    }>;
+    createPRComment(repo: string, prNumber: number, body: string): Promise<{
+        ok: boolean;
+        status: number;
+        data: {
+            id: number;
+            html_url: string;
+            message?: string;
+        };
+    }>;
+    deletePRReviewComment(repo: string, commentId: number): Promise<{
+        ok: boolean;
+        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;
+        data: any;
+    }>;
+    unstarRepo(repo: string): Promise<{
+        ok: boolean;
+        status: number;
+        data: any;
+    }>;
+    isStarred(repo: string): Promise<boolean>;
+    forkRepo(repo: string): Promise<{
+        ok: boolean;
+        status: number;
+        data: any;
+    }>;
+    /** 解析私钥：PEM字符串 或 文件路径 */
+    private resolvePrivateKey;
+    /** 生成 GitHub App JWT（有效期 10 分钟） */
+    static createJWT(appId: string | number, privateKey: string): string;
+    /** 使用 JWT 获取指定 Installation 的 Access Token（有效期 1 小时） */
+    refreshInstallationToken(installationId: number): Promise<void>;
+    /** 发现所有 App 安装及其可访问的仓库 */
+    syncInstallations(): Promise<void>;
+    /** 当前是否使用 App 认证 */
+    get isAppAuth(): boolean;
+    /** 所有已发现的安装 */
+    get installations(): {
+        id: number;
+        account: {
+            login: string;
+            type: string;
+        };
+        target_type: string;
+    }[];
+    /** App 的 slug（verifyAuth 后可用） */
+    private _appSlug;
+    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 条件请求）
+     * @returns events 数组 + 新 etag；若 304 未修改则 events 为空
+     */
+    listRepoEvents(repo: string, etag?: string): Promise<{
+        events: any[];
+        etag: string | null;
+    }>;
+    /**
+     * 第一步：请求设备码
+     * GitHub App 不需要 scope 参数（权限由 App 设置决定），OAuth App 可传 scope。
+     * 注意：Device Flow 端点在 github.com（而非 api.github.com），需确保网络可达。
+     * @returns device_code, user_code, verification_uri, expires_in, interval
+     */
+    static deviceFlowRequestCode(clientId: string, host?: string): Promise<{
+        device_code: string;
+        user_code: string;
+        verification_uri: string;
+        expires_in: number;
+        interval: number;
+    }>;
+    /**
+     * 第二步：轮询等待用户授权
+     * @returns access_token 或 null（超时/拒绝）
+     */
+    static deviceFlowPollToken(clientId: string, deviceCode: string, interval?: number, expiresIn?: number, host?: string): Promise<{
+        access_token: string;
+        token_type: string;
+        scope: string;
+    } | null>;
+}

package/lib/{src/gh-client.js → gh-client.js}

@@ -328,7 +328,7 @@ export class GhClient {
     }
     buildCloneUrl(repo, token) {
         const host = this.host || 'github.com';
-        return `https://x-access-token:${token}@${host}/${repo}.git`;
+        return `https://x-access-token:${encodeURIComponent(token)}@${host}/${repo}.git`;
     }
     async resolveBotUserId() {
         if (this._botUserId != null)
@@ -594,4 +594,3 @@ export class GhClient {
         return null;
     }
 }
-//# sourceMappingURL=gh-client.js.map

package/lib/github-agent-deps.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Agent tool deps for github.
+ * Endpoints register themselves on start; tools look up by config name / endpoint id.
+ */
+import type { GhClient } from './gh-client.js';
+import type { ResolvedGithubConfig } from './protocol.js';
+import type { WorkspaceManager } from './workspace-manager.js';
+export interface GithubAgentEndpoint {
+    readonly name: string;
+    readonly gh: GhClient;
+    readonly config: ResolvedGithubConfig;
+    getAPI(): GhClient;
+    getUserOrDefaultAPI(platform?: string, platformUid?: string): Promise<GhClient | null>;
+    getClientId(): string | null;
+    getHost(): string | undefined;
+    getAppSlug(): string | null;
+    getInstallations(): Array<{
+        id: number;
+        account: {
+            login: string;
+            type: string;
+        };
+        target_type: string;
+    }>;
+    getWorkspaceManager(): WorkspaceManager;
+    /** DatabaseHost wired at endpoint creation (optional). */
+    getDatabase?(): unknown;
+}
+export interface GithubAgentDeps {
+    getEndpoint: (endpointId?: string) => GithubAgentEndpoint;
+    /** Alias kept for existing agent handlers that call getAdapter(). */
+    getAdapter: () => GithubAgentEndpoint;
+    getWorkspaceManager: () => WorkspaceManager;
+    getDatabase?: () => {
+        models?: Map<string, unknown>;
+    } | null | undefined;
+    logger?: {
+        debug: (...args: unknown[]) => void;
+        warn: (...args: unknown[]) => void;
+        error: (...args: unknown[]) => void;
+    };
+}
+export declare function registerGithubAgentEndpoint(endpointId: string, endpoint: GithubAgentEndpoint): () => void;
+/** Optional override used by tests / transitional callers. Pass `null` to clear. */
+export declare function setGithubAgentDeps(deps: GithubAgentDeps | null): void;
+export declare function getGithubAgentDeps(): GithubAgentDeps;
+export declare function getAdapter(): GithubAgentEndpoint;

package/lib/github-agent-deps.js

@@ -0,0 +1,43 @@
+/**
+ * Agent tool deps for github.
+ * Endpoints register themselves on start; tools look up by config name / endpoint id.
+ */
+const endpoints = new Map();
+let override = null;
+export function registerGithubAgentEndpoint(endpointId, endpoint) {
+    endpoints.set(endpointId, endpoint);
+    return () => {
+        if (endpoints.get(endpointId) === endpoint) {
+            endpoints.delete(endpointId);
+        }
+    };
+}
+/** Optional override used by tests / transitional callers. Pass `null` to clear. */
+export function setGithubAgentDeps(deps) {
+    override = deps;
+}
+function lookup(endpointId) {
+    if (endpointId) {
+        const registered = endpoints.get(endpointId);
+        if (!registered)
+            throw new Error(`Endpoint ${endpointId} 不存在`);
+        return registered;
+    }
+    const first = endpoints.values().next().value;
+    if (!first)
+        throw new Error('github agent deps not initialized');
+    return first;
+}
+export function getGithubAgentDeps() {
+    if (override)
+        return override;
+    return {
+        getEndpoint: lookup,
+        getAdapter: () => lookup(),
+        getWorkspaceManager: () => lookup().getWorkspaceManager(),
+        getDatabase: () => lookup().getDatabase?.(),
+    };
+}
+export function getAdapter() {
+    return getGithubAgentDeps().getAdapter();
+}

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

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

package/lib/{src/github-bot-handlers.js → github-bot-handlers.js}

@@ -75,4 +75,3 @@ export async function executeGithubCreatePr(args, commMessage) {
     }
     return `✅ PR #${r.data.number} 已创建\n🔗 ${r.data.html_url}`;
 }
-//# sourceMappingURL=github-bot-handlers.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/{src/github-channel-context.js → github-channel-context.js}

@@ -29,4 +29,3 @@ export async function resolveWorkspaceBranch(gh, ctx) {
 export function formatChannelContext(ctx) {
     return buildChannelId(ctx.repo, ctx.type, ctx.number);
 }
-//# sourceMappingURL=github-channel-context.js.map

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

@@ -0,0 +1,17 @@
+import type { Message } from 'zhin.js';
+export declare function executeGithubStar(args: {
+    action: 'star' | 'unstar' | 'check';
+    repo: string;
+}, commMessage?: Message): Promise<string>;
+export declare function executeGithubBind(_args: Record<string, never>, commMessage?: Message): Promise<string>;
+export declare function executeGithubUnbind(_args: Record<string, never>, commMessage?: Message): Promise<string>;
+export declare function executeGithubWhoami(_args: Record<string, never>, commMessage?: Message): Promise<string>;
+export declare function executeGithubInstall(): Promise<string>;
+export declare function executeGithubSubscribe(args: {
+    repo: string;
+    events?: string;
+}, commMessage?: Message): Promise<string>;
+export declare function executeGithubUnsubscribe(args: {
+    repo: string;
+}, commMessage?: Message): Promise<string>;
+export declare function executeGithubSubscriptions(_args: Record<string, never>, commMessage?: Message): Promise<string>;