@zhin.js/adapter-github 3.0.2 → 3.0.3

package/src/index.ts

@@ -1,141 +1,59 @@
-/**
- * GitHub 适配器入口：类型扩展、模型、导出、注册
- */
-import { formatCompact, type Context, type Plugin, usePlugin } from 'zhin.js';
-import path from 'node:path';
-import { registerAgentPromptContributor, unregisterAgentPromptContributor } from 'zhin.js/agent';
-import { createGithubAgentPromptContributor } from './agent-prompt.js';
-import { GitHubAdapter } from './adapter.js';
-import { registerGithubMcp } from './register-github-mcp.js';
-import { setGithubAgentDeps } from './github-agent-deps.js';
-import { WorkspaceManager } from './workspace-manager.js';
-import type { GitHubEndpointConfig } from './types.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 GithubAdapterConfig,
+  type GithubInboundComment,
+  type GithubWireSegment,
+  type ResolvedGithubConfig,
+} from './protocol.js';
 
 export * from './types.js';
-export { GitHubEndpoint, parseMarkdown, toMarkdown, enrichGithubInboundMessage, shouldAutoReplyRepo } from './endpoint.js';
-export { GitHubAdapter } from './adapter.js';
-export { GhClient } from './gh-client.js';
-export { WorkspaceManager } from './workspace-manager.js';
-export { parseMessageChannel, issueBranchName, resolveWorkspaceBranch } from './github-channel-context.js';
-
-const plugin = usePlugin();
-const { provide, defineModel, useContext, logger } = plugin;
-
-registerGithubMcp(plugin);
-
-defineModel('github_subscriptions', {
-  id: { type: 'integer', primary: true },
-  repo: { type: 'text', nullable: false },
-  events: { type: 'json', default: [] },
-  target_id: { type: 'text', nullable: false },
-  target_type: { type: 'text', nullable: false },
-  adapter: { type: 'text', nullable: false },
-  endpoint: { type: 'text', nullable: false },
-});
 
-defineModel('github_events', {
-  id: { type: 'integer', primary: true },
-  repo: { type: 'text', nullable: false },
-  event_type: { type: 'text', nullable: false },
-  payload: { type: 'json', default: {} },
-});
+export {
+  getAdapter,
+  getGithubAgentDeps,
+  registerGithubAgentEndpoint,
+  setGithubAgentDeps,
+  type GithubAgentDeps,
+  type GithubAgentEndpoint,
+} from './github-agent-deps.js';
 
-defineModel('github_oauth_users', {
-  id: { type: 'integer', primary: true },
-  platform: { type: 'text', nullable: false },
-  platform_uid: { type: 'text', nullable: false },
-  github_login: { type: 'text', nullable: false },
-  access_token: { type: 'text', nullable: false },
-  created_at: { type: 'integer', default: 0 },
-});
-
-provide({
-  name: 'github',
-  description: 'GitHub Adapter — Issues/PRs as chat channels, full repo management via gh CLI',
-  mounted: async (p: Plugin) => {
-    registerAgentPromptContributor(createGithubAgentPromptContributor());
-    const adapter = new GitHubAdapter(p);
-    await adapter.start();
-    return adapter;
-  },
-  dispose: async (adapter: GitHubAdapter) => {
-    unregisterAgentPromptContributor('github');
-    await adapter.stop();
-  },
-} as Context<'github'>);
-
-// 混合模式：有 router + webhook_secret → Webhook 实时；否则 → 轮询降级
-useContext('github', (adapter) => {
-  if (adapter.hasWebhookConfig) {
-    const router = plugin.inject('router');
-    if (router) {
-      adapter.setupWebhook(router);
-      logger.debug(formatCompact({ op: 'events', source: 'webhook' }));
-    } else {
-      plugin.useContext('router', (r) => {
-        adapter.setupWebhook(r);
-        logger.debug(formatCompact({ op: 'events', source: 'webhook', deferred: true }));
-      });
-    }
-  }
-  if (!adapter.webhookActive) {
-    adapter.startPolling();
-    logger.debug(formatCompact({ op: 'events', source: 'poll' }));
-  }
-  return () => adapter.stopPolling();
-});
-
-useContext('tool', 'github', (_toolService, adapter: GitHubAdapter) => {
-  // Endpoint 由 App 从 zhin.config endpoints 注入，可能晚于本回调；懒解析 GhClient。
-  let workspaceManager: WorkspaceManager | null = null;
-  setGithubAgentDeps({
-    getAdapter: () => adapter,
-    getWorkspaceManager: () => {
-      if (workspaceManager) return workspaceManager;
-      const gh = adapter.getAPI();
-      if (!gh) {
-        throw new Error('GitHub Endpoint 尚未就绪（检查 endpoints 中 github 配置是否已连接）');
-      }
-      const endpoint = adapter.endpoints.values().next().value;
-      const cfg = endpoint?.$config as GitHubEndpointConfig | undefined;
-      const workspaceRoot = cfg?.workspace_root
-        ?? path.join(process.cwd(), 'data', 'github-workspaces');
-      workspaceManager = new WorkspaceManager(gh, workspaceRoot);
-      return workspaceManager;
-    },
-    plugin,
-  });
-  logger.debug('GitHub agent deps initialized (lazy workspace)');
-  return () => {};
-});
-
-logger.debug('GitHub 适配器已加载 (gh CLI 认证)');
+export { GhClient } from './gh-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';

package/src/oauth-users.ts

@@ -0,0 +1,47 @@
+/**
+ * github_oauth_users — SSOT for Runtime user-token binding (gh bind / Endpoint lookup).
+ */
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import type { DatabaseHost } from '@zhin.js/plugin-runtime';
+
+const logger = getLogger('github');
+
+export const GITHUB_OAUTH_USERS_TABLE = 'github_oauth_users';
+
+export const GITHUB_OAUTH_USERS_SCHEMA = {
+  id: { type: 'integer', primary: true },
+  platform: { type: 'text', nullable: false },
+  platform_uid: { type: 'text', nullable: false },
+  github_login: { type: 'text', nullable: false },
+  access_token: { type: 'text', nullable: false },
+  created_at: { type: 'integer', nullable: false },
+} as const;
+
+export function defineGithubOauthUsersTable(
+  host: { define(name: string, definition: Record<string, unknown>): void },
+): void {
+  host.define(GITHUB_OAUTH_USERS_TABLE, { ...GITHUB_OAUTH_USERS_SCHEMA });
+}
+
+/** Resolve a stored PAT/device-flow token; null when DB missing or no row. */
+export async function lookupGithubOauthAccessToken(
+  database: DatabaseHost | undefined,
+  platform: string,
+  platformUid: string,
+): Promise<string | null> {
+  if (!database?.started) return null;
+  const model = database.models.get(GITHUB_OAUTH_USERS_TABLE);
+  if (!model) return null;
+  try {
+    const rows = await model.select().where({ platform, platform_uid: platformUid });
+    const token = rows[0]?.access_token;
+    return typeof token === 'string' && token.trim() ? token : null;
+  } catch (error) {
+    logger.debug(formatCompact({
+      op: 'oauth_lookup_fail',
+      platform,
+      error: error instanceof Error ? error.message : String(error),
+    }));
+    return null;
+  }
+}

package/src/protocol.ts

@@ -0,0 +1,367 @@
+/**
+ * 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 {
+  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 name?: 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 name: 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;
+}
+
+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 name = (typeof config.name === 'string' && config.name)
+    || (typeof entry?.name === 'string' && entry.name)
+    || 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',
+    name,
+    ...(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 MessageGateway.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':
+        return item.data?.url ? `![image](${item.data.url})` : '[image]';
+      case 'link':
+        return `[${item.data?.text || item.data?.url || ''}](${item.data?.url || ''})`;
+      default:
+        return String(item.data?.text ?? `[${item.type}]`);
+    }
+  }).join('');
+}
+
+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;
+}