@zhin.js/adapter-github 1.0.0 → 1.1.0

package/src/protocol.ts

@@ -0,0 +1,425 @@
+/**
+ * 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 type { IncomingMessage } from 'node:http';
+import { pickCredential } from 'zhin.js/adapter';
+import { isMediaRef } from '@zhin.js/core';
+import type { ConversationRef } from '@zhin.js/im-contract';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+
+const logger = getLogger('github');
+import {
+  buildChannelId,
+  type GenericWebhookPayload,
+  type IssueCommentPayload,
+  type PRReviewCommentPayload,
+  type PRReviewPayload,
+} from './types.js';
+
+export type {
+  EventType,
+  GenericWebhookPayload,
+  GitHubComment,
+  GitHubEndpointConfig,
+  GitHubIssue,
+  GitHubOAuthUser,
+  GitHubPR,
+  GitHubRepo,
+  GitHubUser,
+  IssueCommentPayload,
+  ParsedChannel,
+  PRReviewCommentPayload,
+  PRReviewPayload,
+  Subscription,
+} from './types.js';
+
+export { buildChannelId, parseChannelId } from './types.js';
+
+/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
+export interface GithubAdapterConfig {
+  readonly id?: string;
+  readonly host?: string;
+  readonly app_id?: string | number;
+  readonly appId?: string | number;
+  readonly private_key?: string;
+  readonly privateKey?: string;
+  readonly webhook_secret?: string;
+  readonly webhookSecret?: string;
+  readonly webhook_path?: string;
+  readonly webhookPath?: string;
+  readonly poll_interval?: number;
+  readonly pollInterval?: number;
+  readonly auto_reply_repos?: readonly string[];
+  readonly autoReplyRepos?: readonly string[];
+  readonly bot_login?: string;
+  readonly botLogin?: string;
+  readonly workspace_root?: string;
+  readonly workspaceRoot?: string;
+  /** Transitional: legacy root `endpoints[]` with `context: github`. */
+  readonly endpoints?: ReadonlyArray<Partial<ResolvedGithubConfig> & {
+    readonly context?: string;
+    readonly app_id?: string | number;
+    readonly private_key?: string;
+    readonly webhook_secret?: string;
+    readonly webhook_path?: string;
+    readonly poll_interval?: number;
+    readonly auto_reply_repos?: readonly string[];
+    readonly bot_login?: string;
+    readonly workspace_root?: string;
+  }>;
+}
+
+export interface ResolvedGithubConfig {
+  readonly context: 'github';
+  readonly id: string;
+  readonly host?: string;
+  readonly appId?: string | number;
+  readonly privateKey?: string;
+  readonly webhookSecret?: string;
+  readonly webhookPath: string;
+  readonly pollInterval: number;
+  readonly autoReplyRepos: readonly string[];
+  readonly botLogin?: string;
+  readonly workspaceRoot?: string;
+}
+
+export interface GithubWireSegment {
+  readonly type: string;
+  readonly data?: Record<string, unknown>;
+}
+
+export interface GithubInboundComment {
+  readonly id: string;
+  readonly channelId: string;
+  readonly sender: string;
+  readonly content: string;
+  readonly repo: string;
+  readonly kind: 'issue_comment' | 'pr_review_comment' | 'pr_review';
+  readonly createdAt: number;
+}
+
+/**
+ * 入站归一化 → ConversationRef：Issue/PR 评论区即仓库容器内的 channel 会话，
+ * 仓库（owner/repo）进 `parent`。出站侧用 `parseChannelId(conversation.id)`
+ * 在平台边界还原 repo/type/number。
+ */
+export function githubInboundConversation(
+  endpointKey: string,
+  comment: GithubInboundComment,
+): ConversationRef {
+  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: GithubAdapterConfig = {}): ResolvedGithubConfig {
+  const entry = config.endpoints?.find((item) => item.context === 'github');
+  const appIdRaw = pickCredential(
+    config.appId != null ? String(config.appId) : undefined,
+    config.app_id != null ? String(config.app_id) : undefined,
+    entry?.appId != null ? String(entry.appId) : undefined,
+    entry?.app_id != null ? String(entry.app_id) : undefined,
+    process.env.GITHUB_APP_ID,
+  );
+  const appId = appIdRaw ? (Number(appIdRaw) || appIdRaw) : undefined;
+  const privateKey = pickCredential(
+    config.privateKey,
+    config.private_key,
+    entry?.privateKey,
+    entry?.private_key,
+  ) || undefined;
+  if (!appId || !privateKey) {
+    throw new TypeError(
+      'GitHub adapter requires app_id + private_key (plugins.<key> or GITHUB_APP_ID)',
+    );
+  }
+  const id = (typeof config.id === 'string' && config.id)
+    || (typeof entry?.id === 'string' && entry.id)
+    || process.env.GITHUB_BOT_NAME
+    || 'github-bot';
+  const webhookSecret = config.webhookSecret ?? config.webhook_secret
+    ?? entry?.webhookSecret ?? entry?.webhook_secret
+    ?? process.env.GITHUB_WEBHOOK_SECRET
+    ?? undefined;
+  const host = config.host ?? entry?.host;
+  const webhookPath = normalizeWebhookPath(
+    config.webhookPath ?? config.webhook_path ?? entry?.webhookPath ?? entry?.webhook_path
+    ?? '/github/webhook',
+  );
+  const pollInterval = Number(
+    config.pollInterval ?? config.poll_interval ?? entry?.pollInterval ?? entry?.poll_interval ?? 60,
+  ) || 60;
+  const autoReplyRepos = [
+    ...(config.autoReplyRepos ?? config.auto_reply_repos
+      ?? entry?.autoReplyRepos ?? entry?.auto_reply_repos ?? []),
+  ];
+  const botLogin = config.botLogin ?? config.bot_login ?? entry?.botLogin ?? entry?.bot_login;
+  const workspaceRoot = config.workspaceRoot ?? config.workspace_root
+    ?? entry?.workspaceRoot ?? entry?.workspace_root;
+
+  return {
+    context: 'github',
+    id,
+    ...(host ? { host } : {}),
+    ...(appId != null ? { appId } : {}),
+    ...(privateKey ? { privateKey } : {}),
+    ...(webhookSecret ? { webhookSecret } : {}),
+    webhookPath,
+    pollInterval,
+    autoReplyRepos,
+    ...(botLogin ? { botLogin } : {}),
+    ...(workspaceRoot ? { workspaceRoot } : {}),
+  };
+}
+
+export function normalizeWebhookPath(path: string): string {
+  const trimmed = path.trim() || '/github/webhook';
+  return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+
+export function shouldAutoReplyRepo(
+  config: Pick<ResolvedGithubConfig, 'autoReplyRepos'>,
+  repo: string,
+): boolean {
+  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: string,
+  config: Pick<ResolvedGithubConfig, 'autoReplyRepos' | 'botLogin'>,
+  botLogin: string | undefined,
+  repo: string,
+): string {
+  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: string): string {
+  return body;
+}
+
+/** Build markdown body for Issue/PR comment send. */
+export function formatOutboundBody(payload: unknown): string {
+  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 as { text?: unknown }).text ?? '');
+    }
+    return String(payload);
+  }
+  return payload.map((seg) => {
+    if (typeof seg === 'string') return seg;
+    const item = seg as GithubWireSegment;
+    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: GithubWireSegment): string {
+  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: string,
+  rawBody: string,
+  signatureHeader: string | undefined,
+): boolean {
+  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: IncomingMessage['headers'],
+  name: string,
+): string {
+  const raw = headers[name] ?? headers[name.toLowerCase()];
+  if (Array.isArray(raw)) return raw[0] ?? '';
+  return raw ?? '';
+}
+
+export async function readTextBody(
+  request: IncomingMessage,
+  options: { readonly limit?: number } = {},
+): Promise<string> {
+  const limit = options.limit ?? 1_048_576;
+  const chunks: Buffer[] = [];
+  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: IssueCommentPayload): GithubInboundComment | null {
+  if (payload.action !== 'created' || !payload.comment) return null;
+  const repo = payload.repository.full_name;
+  const isPR = 'pull_request' in (payload.issue as object);
+  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: PRReviewCommentPayload): GithubInboundComment | null {
+  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: PRReviewPayload): GithubInboundComment | null {
+  if (payload.action !== 'submitted' || !payload.review.body) return null;
+  const repo = payload.repository.full_name;
+  const stateLabel: Record<string, string> = {
+    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: string, p: GenericWebhookPayload): string {
+  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: string): string {
+  return md;
+}

package/src/types.ts

@@ -1,10 +1,10 @@
-// ── Bot 配置 ─────────────────────────────────────────────────────────
+// ── Endpoint 配置 ─────────────────────────────────────────────────────────
 //  基于 gh CLI 认证：需要系统已安装并认证 gh CLI
 //  认证方式：gh auth login
 
-export interface GitHubBotConfig {
+export interface GitHubEndpointConfig {
   context: 'github';
-  /** Bot 标识名称 */
+  /** Endpoint 标识名称 */
   name: string;
   /** GitHub Enterprise 主机名（默认 github.com） */
   host?: string;
@@ -18,6 +18,12 @@ export interface GitHubBotConfig {
   webhook_path?: string;
   /** 事件轮询间隔（秒，默认 60，Webhook 模式下作为降级备选） */
   poll_interval?: number;
+  /** 这些仓库的人类 Issue/PR 评论自动触发 AI（无需 @bot） */
+  auto_reply_repos?: string[];
+  /** 覆盖 App bot 登录名（默认 {slug}[bot]） */
+  bot_login?: string;
+  /** 托管 git 工作区根目录（默认 {cwd}/data/github-workspaces） */
+  workspace_root?: string;
 }
 
 // ── Channel ID ───────────────────────────────────────────────────────
@@ -135,7 +141,7 @@ export interface Subscription {
   target_id: string;
   target_type: 'private' | 'group' | 'channel';
   adapter: string;
-  bot: string;
+  endpoint: string;
 }
 
 // ── Tool Action Types ────────────────────────────────────────────────

package/src/webhook.ts

@@ -0,0 +1,130 @@
+/**
+ * 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 { formatCompact, getLogger } from '@zhin.js/logger';
+import {
+  headerValue,
+  parseIssueCommentInbound,
+  parsePrReviewCommentInbound,
+  parsePrReviewInbound,
+  readTextBody,
+  verifyWebhookSignature,
+  type GithubInboundComment,
+  type IssueCommentPayload,
+  type PRReviewCommentPayload,
+  type PRReviewPayload,
+  type ResolvedGithubConfig,
+} from './protocol.js';
+
+const logger = getLogger('github');
+
+export interface GithubWebhookHandler {
+  readonly config: ResolvedGithubConfig;
+  admitPlatform(name: string, event: unknown): void;
+  admit(comment: GithubInboundComment): void;
+}
+
+export function registerGithubWebhookRoutes(
+  http: HttpHost,
+  handler: GithubWebhookHandler,
+): HttpRouteRegistration[] {
+  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: IncomingMessage,
+  response: ServerResponse,
+  handler: GithubWebhookHandler,
+): Promise<void> {
+  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: unknown;
+    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: string,
+  payload: unknown,
+  handler: GithubWebhookHandler,
+): Promise<void> {
+  if (!payload || typeof payload !== 'object') return;
+  const body = payload as Record<string, unknown>;
+  const repo = (body.repository as { full_name?: string } | undefined)?.full_name;
+  logger.debug(`Webhook: ${event}${(body.action as string) ? `.${body.action}` : ''} ${repo || ''}`);
+  handler.admitPlatform(
+    typeof body.action === 'string' && body.action ? `${event}.${body.action}` : event,
+    payload,
+  );
+
+  if (event === 'issue_comment') {
+    const inbound = parseIssueCommentInbound(payload as IssueCommentPayload);
+    if (inbound) handler.admit(inbound);
+    return;
+  }
+  if (event === 'pull_request_review_comment') {
+    const inbound = parsePrReviewCommentInbound(payload as PRReviewCommentPayload);
+    if (inbound) handler.admit(inbound);
+    return;
+  }
+  if (event === 'pull_request_review') {
+    const inbound = parsePrReviewInbound(payload as PRReviewPayload);
+    if (inbound) handler.admit(inbound);
+  }
+  // Cross-adapter subscription fan-out deferred (needs multi-adapter send in Runtime).
+}