@zhin.js/adapter-github 1.0.1 → 1.1.2

package/lib/protocol.js

@@ -0,0 +1,281 @@
+/**
+ * GitHub webhook / comment helpers — no legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { isMediaRef } from '@zhin.js/im-contract';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('github');
+import { buildChannelId, } from './types.js';
+export { buildChannelId, parseChannelId } from './types.js';
+/**
+ * 入站归一化 → ConversationRef：Issue/PR 评论区即仓库容器内的 channel 会话，
+ * 仓库（owner/repo）进 `parent`。出站侧用 `parseChannelId(conversation.id)`
+ * 在平台边界还原 repo/type/number。
+ */
+export function githubInboundConversation(endpointKey, comment) {
+    return {
+        endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+        kind: 'channel',
+        id: comment.channelId,
+        parent: { kind: 'channel', id: comment.repo },
+    };
+}
+export function resolveGithubConfig(config) {
+    const id = typeof config.id === 'string' ? config.id.trim() : '';
+    if (!id)
+        throw new TypeError('GitHub endpoint requires a non-empty id');
+    const appIdRaw = config.app_id != null ? String(config.app_id).trim() : '';
+    const appId = appIdRaw ? (Number(appIdRaw) || appIdRaw) : undefined;
+    const privateKey = typeof config.private_key === 'string'
+        ? config.private_key.trim()
+        : '';
+    if (!appId || !privateKey) {
+        throw new TypeError('GitHub endpoint requires app_id and private_key');
+    }
+    const webhookSecret = config.webhook_secret;
+    const host = config.host;
+    const webhookPath = normalizeWebhookPath(config.webhook_path ?? '/github/webhook');
+    const autoReplyRepos = [...(config.auto_reply_repos ?? [])];
+    const botLogin = config.bot_login;
+    const workspaceRoot = config.workspace_root ?? 'data/github-workspaces';
+    return {
+        context: 'github',
+        id,
+        ...(host ? { host } : {}),
+        appId,
+        privateKey,
+        ...(webhookSecret ? { webhookSecret } : {}),
+        webhookPath,
+        autoReplyRepos,
+        ...(botLogin ? { botLogin } : {}),
+        workspaceRoot,
+    };
+}
+export function normalizeWebhookPath(path) {
+    const trimmed = path.trim() || '/github/webhook';
+    return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+export function shouldAutoReplyRepo(config, repo) {
+    const list = config.autoReplyRepos;
+    if (!list.length)
+        return false;
+    const key = repo.toLowerCase();
+    return list.some((r) => r.toLowerCase() === key);
+}
+/** Prepend synthetic @bot for auto_reply repos (gateway text path). */
+export function enrichInboundContent(content, config, botLogin, repo) {
+    const login = config.botLogin || botLogin;
+    if (!login || !shouldAutoReplyRepo(config, repo))
+        return content;
+    if (content.includes(`@${login}`))
+        return content;
+    return `@${login} ${content}`;
+}
+/** Build inbound text for OutboundMessageService.receive from markdown/comment body. */
+export function formatInboundContent(body) {
+    return body;
+}
+/** Build markdown body for Issue/PR comment send. */
+export function formatOutboundBody(payload) {
+    if (typeof payload === 'string')
+        return payload;
+    if (payload == null)
+        return '';
+    if (!Array.isArray(payload)) {
+        if (typeof payload === 'object' && payload !== null && 'text' in payload) {
+            return String(payload.text ?? '');
+        }
+        return String(payload);
+    }
+    return payload.map((seg) => {
+        if (typeof seg === 'string')
+            return seg;
+        const item = seg;
+        switch (item.type) {
+            case 'text':
+                return String(item.data?.text ?? '');
+            case 'mention':
+            case 'at':
+                return `@${item.data?.name || item.data?.id || item.data?.target || ''}`;
+            case 'image':
+            case 'audio':
+            case 'video':
+            case 'file':
+                return formatMediaSegment(item);
+            case 'link':
+                return `[${item.data?.text || item.data?.url || ''}](${item.data?.url || ''})`;
+            default:
+                return String(item.data?.text ?? `[${item.type}]`);
+        }
+    }).join('');
+}
+/**
+ * 媒体段 → GitHub markdown（canonical MediaRef 唯一来源）。
+ * GitHub 评论只能消费远程 URL（无上传面），kind=url 直发；
+ * base64 / path / file 不可投递，warn + 丢弃。
+ */
+function formatMediaSegment(seg) {
+    const media = seg.data?.media;
+    if (!isMediaRef(media)) {
+        logger.warn(formatCompact({
+            op: 'github_outbound_media_dropped',
+            type: seg.type,
+            reason: 'missing_media_ref',
+        }));
+        return '';
+    }
+    if (media.kind !== 'url') {
+        logger.warn(formatCompact({
+            op: 'github_outbound_media_dropped',
+            type: seg.type,
+            reason: `unsupported_kind:${media.kind}`,
+        }));
+        return '';
+    }
+    if (seg.type === 'image') {
+        const alt = typeof seg.data?.alt === 'string' && seg.data.alt
+            ? seg.data.alt
+            : media.file_name || 'image';
+        return `![${alt}](${media.value})`;
+    }
+    const label = media.file_name || seg.type;
+    return `[${label}](${media.value})`;
+}
+export function verifyWebhookSignature(secret, rawBody, signatureHeader) {
+    if (!signatureHeader?.startsWith('sha256='))
+        return false;
+    const expected = `sha256=${createHmac('sha256', secret).update(rawBody).digest('hex')}`;
+    try {
+        const a = Buffer.from(signatureHeader);
+        const b = Buffer.from(expected);
+        if (a.length !== b.length)
+            return false;
+        return timingSafeEqual(a, b);
+    }
+    catch {
+        return false;
+    }
+}
+export function headerValue(headers, name) {
+    const raw = headers[name] ?? headers[name.toLowerCase()];
+    if (Array.isArray(raw))
+        return raw[0] ?? '';
+    return raw ?? '';
+}
+export async function readTextBody(request, options = {}) {
+    const limit = options.limit ?? 1_048_576;
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buffer.length;
+        if (size > limit) {
+            request.destroy();
+            throw new Error(`Request body exceeds ${limit} bytes`);
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+export function parseIssueCommentInbound(payload) {
+    if (payload.action !== 'created' || !payload.comment)
+        return null;
+    const repo = payload.repository.full_name;
+    const isPR = 'pull_request' in payload.issue;
+    return {
+        id: String(payload.comment.id),
+        channelId: buildChannelId(repo, isPR ? 'pr' : 'issue', payload.issue.number),
+        sender: payload.sender.login,
+        content: payload.comment.body,
+        repo,
+        kind: 'issue_comment',
+        createdAt: new Date(payload.comment.created_at).getTime(),
+    };
+}
+export function parsePrReviewCommentInbound(payload) {
+    if (payload.action !== 'created' || !payload.comment)
+        return null;
+    const repo = payload.repository.full_name;
+    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 {
+        id: String(payload.comment.id),
+        channelId: buildChannelId(repo, 'pr', payload.pull_request.number),
+        sender: payload.sender.login,
+        content: body,
+        repo,
+        kind: 'pr_review_comment',
+        createdAt: new Date(payload.comment.created_at).getTime(),
+    };
+}
+export function parsePrReviewInbound(payload) {
+    if (payload.action !== 'submitted' || !payload.review.body)
+        return null;
+    const repo = payload.repository.full_name;
+    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 {
+        id: String(payload.review.id),
+        channelId: buildChannelId(repo, 'pr', payload.pull_request.number),
+        sender: payload.sender.login,
+        content: body,
+        repo,
+        kind: 'pr_review',
+        createdAt: new Date(payload.review.submitted_at).getTime(),
+    };
+}
+export function formatNotification(event, p) {
+    const repo = p.repository.full_name;
+    const sender = p.sender.login;
+    const repoUrl = p.repository.html_url;
+    switch (event) {
+        case 'push': {
+            const branch = p.ref?.replace('refs/heads/', '') || '?';
+            const commits = p.commits || [];
+            const compareUrl = commits.length >= 2
+                ? `${repoUrl}/compare/${commits[0].id.substring(0, 12)}...${commits[commits.length - 1].id.substring(0, 12)}`
+                : commits.length === 1 ? `${repoUrl}/commit/${commits[0].id}` : '';
+            let msg = `📦 ${repo}\n🌿 ${sender} pushed ${commits.length} commit(s) to \`${branch}\`\n`;
+            if (commits.length) {
+                msg += '\n';
+                msg += commits.slice(0, 5).map((c) => `  • [\`${c.id.substring(0, 7)}\`](${repoUrl}/commit/${c.id}) ${c.message.split('\n')[0]}`).join('\n');
+                if (commits.length > 5)
+                    msg += `\n  ... +${commits.length - 5} more`;
+            }
+            if (compareUrl)
+                msg += `\n\n🔗 ${compareUrl}`;
+            return msg;
+        }
+        case 'issues': {
+            const i = p.issue;
+            const act = p.action === 'opened' ? '📝 opened' : p.action === 'closed' ? '✅ closed' : `🔄 ${p.action || 'updated'}`;
+            return `🐛 ${repo}\n👤 ${sender} ${act} issue #${i.number}\n📌 ${i.title}\n🔗 ${i.html_url}`;
+        }
+        case 'star': {
+            const starred = p.action !== 'deleted';
+            return `${starred ? '⭐' : '💔'} ${repo}\n👤 ${sender} ${starred ? 'starred' : 'unstarred'}\n🔗 ${repoUrl}`;
+        }
+        case 'fork':
+            return `🍴 ${repo}\n👤 ${sender} forked → ${p.forkee.full_name}\n🔗 ${p.forkee.html_url}`;
+        case 'pull_request': {
+            const pr = p.pull_request;
+            const act = p.action === 'opened' ? '📝 opened'
+                : p.action === 'closed' ? (pr.state === 'closed' ? '❌ closed' : '✅ merged')
+                    : `🔄 ${p.action || 'updated'}`;
+            return `🔀 ${repo}\n👤 ${sender} ${act} PR #${pr.number}\n📌 ${pr.title}\n🌿 ${pr.head.ref} → ${pr.base.ref}\n🔗 ${pr.html_url}`;
+        }
+        default:
+            return `📬 ${repo}\n📡 ${event}${p.action ? ` (${p.action})` : ''} by ${sender}\n🔗 ${repoUrl}`;
+    }
+}
+/** Parse @mentions in markdown into a flat display string (gateway text path). */
+export function parseMarkdownMentions(md) {
+    return md;
+}

package/lib/types.d.ts

@@ -1,20 +1,3 @@
-export interface GitHubEndpointConfig {
-    context: 'github';
-    /** Endpoint 标识名称 */
-    name: string;
-    /** GitHub Enterprise 主机名（默认 github.com） */
-    host?: string;
-    /** GitHub App ID */
-    app_id?: string | number;
-    /** GitHub App 私钥（PEM 内容或文件路径） */
-    private_key?: string;
-    /** Webhook Secret（配置后启用 Webhook 接收事件，不配置则使用轮询） */
-    webhook_secret?: string;
-    /** Webhook 路由路径（默认 /github/webhook） */
-    webhook_path?: string;
-    /** 事件轮询间隔（秒，默认 60，Webhook 模式下作为降级备选） */
-    poll_interval?: number;
-}
 export interface ParsedChannel {
     repo: string;
     type: 'issue' | 'pr';
@@ -141,4 +124,3 @@ export interface GitHubOAuthUser {
     /** 绑定时间 (ms) */
     created_at: number;
 }
-//# sourceMappingURL=types.d.ts.map

package/lib/types.js

@@ -1,6 +1,5 @@
-// ── Endpoint 配置 ─────────────────────────────────────────────────────────
-//  基于 gh CLI 认证：需要系统已安装并认证 gh CLI
-//  认证方式：gh auth login
+// ── Channel ID ───────────────────────────────────────────────────────
+//  格式: {owner}/{repo}/issues/{number} 或 {owner}/{repo}/pull/{number}
 export function parseChannelId(channelId) {
     const issueMatch = channelId.match(/^(.+?\/.+?)\/issues\/(\d+)$/);
     if (issueMatch)
@@ -13,4 +12,3 @@ export function parseChannelId(channelId) {
 export function buildChannelId(repo, type, number) {
     return type === 'issue' ? `${repo}/issues/${number}` : `${repo}/pull/${number}`;
 }
-//# sourceMappingURL=types.js.map

package/lib/webhook.d.ts

@@ -0,0 +1,14 @@
+/**
+ * GitHub webhook HTTP: verify → parse → admit inbound comments.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import { type GithubInboundComment, type ResolvedGithubConfig } from './protocol.js';
+export interface GithubWebhookHandler {
+    readonly config: ResolvedGithubConfig;
+    admitPlatform(name: string, event: unknown): void;
+    admit(comment: GithubInboundComment): void;
+}
+export declare function registerGithubWebhookRoutes(http: HttpHost, handler: GithubWebhookHandler): HttpRouteRegistration[];
+export declare function handleGithubWebhookRequest(request: IncomingMessage, response: ServerResponse, handler: GithubWebhookHandler): Promise<void>;
+export declare function dispatchGithubWebhookPayload(event: string, payload: unknown, handler: GithubWebhookHandler): Promise<void>;

package/lib/webhook.js

@@ -0,0 +1,88 @@
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { headerValue, parseIssueCommentInbound, parsePrReviewCommentInbound, parsePrReviewInbound, readTextBody, verifyWebhookSignature, } from './protocol.js';
+const logger = getLogger('github');
+export function registerGithubWebhookRoutes(http, handler) {
+    const routePath = handler.config.webhookPath;
+    return [
+        http.route('POST', routePath, async (request, response) => {
+            await handleGithubWebhookRequest(request, response, handler);
+        }, { summary: 'GitHub webhook', tags: ['github'] }),
+    ];
+}
+export async function handleGithubWebhookRequest(request, response, handler) {
+    const secret = handler.config.webhookSecret;
+    if (!secret) {
+        response.writeHead(503, { 'Content-Type': 'application/json' });
+        response.end(JSON.stringify({ error: 'Webhook not configured' }));
+        return;
+    }
+    const signature = headerValue(request.headers, 'x-hub-signature-256');
+    const event = headerValue(request.headers, 'x-github-event');
+    const deliveryId = headerValue(request.headers, 'x-github-delivery');
+    if (!signature || !event) {
+        response.writeHead(400, { 'Content-Type': 'application/json' });
+        response.end(JSON.stringify({ error: 'Missing signature or event header' }));
+        return;
+    }
+    try {
+        const rawBody = await readTextBody(request);
+        if (!verifyWebhookSignature(secret, rawBody, signature)) {
+            logger.warn(formatCompact({
+                op: 'webhook',
+                ok: false,
+                error: 'invalid signature',
+                delivery: deliveryId,
+            }));
+            response.writeHead(401, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ error: 'Invalid signature' }));
+            return;
+        }
+        let payload;
+        try {
+            payload = rawBody ? JSON.parse(rawBody) : {};
+        }
+        catch {
+            response.writeHead(400, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ error: 'Invalid JSON' }));
+            return;
+        }
+        response.writeHead(200, { 'Content-Type': 'application/json' });
+        response.end(JSON.stringify({ ok: true }));
+        void dispatchGithubWebhookPayload(event, payload, handler).catch((e) => {
+            logger.error(`Webhook 事件处理失败 (${event}):`, e);
+        });
+    }
+    catch (error) {
+        logger.error('Webhook error:', error);
+        if (!response.headersSent) {
+            response.writeHead(500, { 'Content-Type': 'application/json' });
+            response.end(JSON.stringify({ error: 'Internal Server Error' }));
+        }
+    }
+}
+export async function dispatchGithubWebhookPayload(event, payload, handler) {
+    if (!payload || typeof payload !== 'object')
+        return;
+    const body = payload;
+    const repo = body.repository?.full_name;
+    logger.debug(`Webhook: ${event}${body.action ? `.${body.action}` : ''} ${repo || ''}`);
+    handler.admitPlatform(typeof body.action === 'string' && body.action ? `${event}.${body.action}` : event, payload);
+    if (event === 'issue_comment') {
+        const inbound = parseIssueCommentInbound(payload);
+        if (inbound)
+            handler.admit(inbound);
+        return;
+    }
+    if (event === 'pull_request_review_comment') {
+        const inbound = parsePrReviewCommentInbound(payload);
+        if (inbound)
+            handler.admit(inbound);
+        return;
+    }
+    if (event === 'pull_request_review') {
+        const inbound = parsePrReviewInbound(payload);
+        if (inbound)
+            handler.admit(inbound);
+    }
+    // Cross-adapter subscription fan-out deferred (needs multi-adapter send in Runtime).
+}

package/lib/workspace-manager.d.ts

@@ -0,0 +1,21 @@
+import type { GhClient, GitHubBotIdentity } from './gh-client.js';
+/**
+ * 校验 GitHub "owner/name" 全名，防止路径穿越与 git 选项注入。
+ * 返回通过校验的原值，便于调用方直接使用「已消毒」的变量。
+ */
+export declare function assertRepoFullName(repo: string): string;
+/**
+ * 校验 git ref 名称，拒绝选项注入（`-` 前缀）与 git 非法字符。
+ */
+export declare function assertGitRefName(ref: string): string;
+export declare class WorkspaceManager {
+    private readonly gh;
+    private readonly rootDir;
+    constructor(gh: GhClient, rootDir: string);
+    getRepoPath(repo: string): string;
+    private runGit;
+    configureBotGit(repoPath: string, identity: GitHubBotIdentity): Promise<void>;
+    ensureRepo(repo: string): Promise<string>;
+    checkoutBranch(repo: string, branch: string, baseRef: string): Promise<string>;
+    commitAndPush(repo: string, branch: string, message: string): Promise<string>;
+}

package/lib/workspace-manager.js

@@ -0,0 +1,154 @@
+/**
+ * Managed git workspaces for GitHub App Bot development flow.
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+const REPO_FULL_NAME_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const GIT_REF_ILLEGAL_CHARS = new Set('~^:?*[\\`;');
+function containsIllegalGitRefCharacter(ref) {
+    return [...ref].some((character) => {
+        const code = character.charCodeAt(0);
+        return code <= 31
+            || code === 127
+            || /\s/u.test(character)
+            || GIT_REF_ILLEGAL_CHARS.has(character);
+    });
+}
+/**
+ * 校验 GitHub "owner/name" 全名，防止路径穿越与 git 选项注入。
+ * 返回通过校验的原值，便于调用方直接使用「已消毒」的变量。
+ */
+export function assertRepoFullName(repo) {
+    if (typeof repo !== 'string' ||
+        !REPO_FULL_NAME_RE.test(repo) ||
+        repo.split('/').some((seg) => seg === '' || seg.startsWith('-') || /^\.+$/.test(seg))) {
+        throw new TypeError(`非法的仓库全名: ${JSON.stringify(repo)}`);
+    }
+    return repo;
+}
+/**
+ * 校验 git ref 名称，拒绝选项注入（`-` 前缀）与 git 非法字符。
+ */
+export function assertGitRefName(ref) {
+    if (typeof ref !== 'string' || ref.length === 0) {
+        throw new TypeError(`非法的 git ref: ${JSON.stringify(ref)}`);
+    }
+    if (ref.startsWith('-') ||
+        ref.includes('..') ||
+        containsIllegalGitRefCharacter(ref) ||
+        ref.endsWith('/') ||
+        ref.endsWith('.')) {
+        throw new TypeError(`非法的 git ref: ${JSON.stringify(ref)}`);
+    }
+    return ref;
+}
+export class WorkspaceManager {
+    gh;
+    rootDir;
+    constructor(gh, rootDir) {
+        this.gh = gh;
+        this.rootDir = rootDir;
+    }
+    getRepoPath(repo) {
+        repo = assertRepoFullName(repo);
+        const [owner, name] = repo.split('/');
+        return path.join(this.rootDir, owner, name);
+    }
+    runGit(cwd, args, env) {
+        return new Promise((resolve, reject) => {
+            const proc = spawn('git', args, {
+                cwd,
+                stdio: ['ignore', 'pipe', 'pipe'],
+                env: { ...process.env, ...env },
+            });
+            let stdout = '';
+            let stderr = '';
+            proc.stdout.on('data', (d) => { stdout += d.toString(); });
+            proc.stderr.on('data', (d) => { stderr += d.toString(); });
+            proc.on('error', (err) => {
+                if (err.code === 'ENOENT')
+                    reject(new Error('git 未安装'));
+                else
+                    reject(err);
+            });
+            proc.on('close', (code) => {
+                if (code === 0)
+                    resolve(stdout);
+                else
+                    reject(new Error(stderr.trim() || `git ${args.join(' ')} failed (${code})`));
+            });
+        });
+    }
+    configureBotGit(repoPath, identity) {
+        return Promise.all([
+            this.runGit(repoPath, ['config', 'user.name', identity.login]),
+            this.runGit(repoPath, ['config', 'user.email', identity.email]),
+        ]).then(() => undefined);
+    }
+    async ensureRepo(repo) {
+        repo = assertRepoFullName(repo);
+        if (!this.gh.isAppAuth) {
+            throw new Error('GitHub App 认证未配置，无法托管工作区');
+        }
+        const token = await this.gh.ensureInstallationTokenForRepo(repo);
+        if (!token)
+            throw new Error(`无法获取 ${repo} 的 Installation Token`);
+        const repoPath = this.getRepoPath(repo);
+        fs.mkdirSync(path.dirname(repoPath), { recursive: true });
+        const identity = await this.gh.getBotIdentity();
+        if (!identity)
+            throw new Error('无法解析 GitHub App Bot 身份');
+        const cloneUrl = this.gh.buildCloneUrl(repo, token);
+        if (!fs.existsSync(path.join(repoPath, '.git'))) {
+            await this.runGit(path.dirname(repoPath), ['clone', cloneUrl, path.basename(repoPath)]);
+        }
+        else {
+            await this.runGit(repoPath, ['remote', 'set-url', 'origin', cloneUrl]);
+            await this.runGit(repoPath, ['fetch', 'origin', '--prune']);
+        }
+        await this.configureBotGit(repoPath, identity);
+        return repoPath;
+    }
+    async checkoutBranch(repo, branch, baseRef) {
+        repo = assertRepoFullName(repo);
+        branch = assertGitRefName(branch);
+        baseRef = assertGitRefName(baseRef);
+        const repoPath = await this.ensureRepo(repo);
+        const localBranches = await this.runGit(repoPath, ['branch', '--list', branch]);
+        if (localBranches.trim()) {
+            await this.runGit(repoPath, ['checkout', branch]);
+            await this.runGit(repoPath, ['pull', '--rebase', 'origin', branch]).catch(async () => {
+                await this.runGit(repoPath, ['fetch', 'origin', branch]);
+            });
+            return repoPath;
+        }
+        const remoteBranch = await this.runGit(repoPath, ['ls-remote', '--heads', 'origin', branch]);
+        if (remoteBranch.trim()) {
+            await this.runGit(repoPath, ['checkout', '-B', branch, `origin/${branch}`]);
+            return repoPath;
+        }
+        await this.runGit(repoPath, ['fetch', 'origin', baseRef]);
+        await this.runGit(repoPath, ['checkout', '-B', branch, `origin/${baseRef}`]);
+        return repoPath;
+    }
+    async commitAndPush(repo, branch, message) {
+        repo = assertRepoFullName(repo);
+        branch = assertGitRefName(branch);
+        const repoPath = this.getRepoPath(repo);
+        if (!fs.existsSync(repoPath)) {
+            throw new Error(`工作区不存在: ${repoPath}，请先 github_prepare_workspace`);
+        }
+        const token = await this.gh.ensureInstallationTokenForRepo(repo);
+        if (!token)
+            throw new Error('Installation Token 不可用');
+        await this.runGit(repoPath, ['remote', 'set-url', 'origin', this.gh.buildCloneUrl(repo, token)]);
+        const status = await this.runGit(repoPath, ['status', '--porcelain']);
+        if (!status.trim())
+            return '没有可提交的变更';
+        await this.runGit(repoPath, ['add', '-A']);
+        await this.runGit(repoPath, ['commit', '-m', message]);
+        await this.runGit(repoPath, ['push', '-u', 'origin', branch]);
+        return `已 push 到 origin/${branch}`;
+    }
+}