@spaceflow/core 0.1.1

package/src/shared/git-provider/adapters/index.ts

@@ -0,0 +1,3 @@
+export * from "./gitea.adapter";
+export * from "./github.adapter";
+export * from "./gitlab.adapter";

package/src/shared/git-provider/detect-provider.spec.ts

@@ -0,0 +1,195 @@
+import { detectProvider } from "./detect-provider";
+
+describe("detectProvider", () => {
+  // ============ 显式指定 ============
+
+  describe("GIT_PROVIDER_TYPE 显式指定", () => {
+    it("指定 github 时应返回 github", () => {
+      const result = detectProvider({ GIT_PROVIDER_TYPE: "github", GITHUB_TOKEN: "ghp-xxx" });
+      expect(result.provider).toBe("github");
+      expect(result.source).toContain("GIT_PROVIDER_TYPE");
+    });
+
+    it("指定 gitea 时应返回 gitea", () => {
+      const result = detectProvider({ GIT_PROVIDER_TYPE: "gitea", GITEA_TOKEN: "tok" });
+      expect(result.provider).toBe("gitea");
+      expect(result.source).toContain("GIT_PROVIDER_TYPE");
+    });
+
+    it("指定 gitlab 时应返回 gitlab", () => {
+      const result = detectProvider({ GIT_PROVIDER_TYPE: "gitlab", GITLAB_TOKEN: "tok" });
+      expect(result.provider).toBe("gitlab");
+      expect(result.source).toContain("GIT_PROVIDER_TYPE");
+    });
+
+    it("指定无效值时应走自动检测", () => {
+      const result = detectProvider({ GIT_PROVIDER_TYPE: "bitbucket" });
+      expect(result.provider).toBe("github");
+      expect(result.source).toBe("默认");
+    });
+  });
+
+  // ============ GITEA_TOKEN 检测 ============
+
+  describe("GITEA_TOKEN 检测", () => {
+    it("有 GITEA_TOKEN 时应识别为 gitea", () => {
+      const result = detectProvider({
+        GITEA_TOKEN: "tok",
+        GITEA_SERVER_URL: "https://gitea.example.com",
+      });
+      expect(result.provider).toBe("gitea");
+      expect(result.serverUrl).toBe("https://gitea.example.com");
+      expect(result.token).toBe("tok");
+      expect(result.source).toContain("GITEA_TOKEN");
+    });
+
+    it("GITEA_TOKEN 优先于 GITHUB_TOKEN", () => {
+      const result = detectProvider({
+        GITEA_TOKEN: "gitea-tok",
+        GITHUB_TOKEN: "gh-tok",
+        GITHUB_SERVER_URL: "https://github.com",
+      });
+      expect(result.provider).toBe("gitea");
+      expect(result.token).toBe("gitea-tok");
+    });
+  });
+
+  // ============ GITLAB_TOKEN / CI_JOB_TOKEN 检测 ============
+
+  describe("GitLab 检测", () => {
+    it("有 GITLAB_TOKEN 时应识别为 gitlab", () => {
+      const result = detectProvider({
+        GITLAB_TOKEN: "glpat-xxx",
+        CI_SERVER_URL: "https://gitlab.example.com",
+      });
+      expect(result.provider).toBe("gitlab");
+      expect(result.serverUrl).toBe("https://gitlab.example.com");
+      expect(result.token).toBe("glpat-xxx");
+      expect(result.source).toContain("GITLAB_TOKEN");
+    });
+
+    it("有 CI_JOB_TOKEN 时应识别为 gitlab", () => {
+      const result = detectProvider({
+        CI_JOB_TOKEN: "ci-tok",
+        CI_SERVER_URL: "https://gitlab.company.com",
+      });
+      expect(result.provider).toBe("gitlab");
+      expect(result.serverUrl).toBe("https://gitlab.company.com");
+      expect(result.token).toBe("ci-tok");
+      expect(result.source).toContain("CI_JOB_TOKEN");
+    });
+
+    it("未指定 CI_SERVER_URL 时应使用默认 gitlab.com", () => {
+      const result = detectProvider({ GITLAB_TOKEN: "glpat-xxx" });
+      expect(result.provider).toBe("gitlab");
+      expect(result.serverUrl).toBe("https://gitlab.com");
+    });
+
+    it("GITEA_TOKEN 优先于 GITLAB_TOKEN", () => {
+      const result = detectProvider({
+        GITEA_TOKEN: "gitea-tok",
+        GITLAB_TOKEN: "gl-tok",
+      });
+      expect(result.provider).toBe("gitea");
+    });
+  });
+
+  // ============ GITHUB_TOKEN 检测 ============
+
+  describe("GITHUB_TOKEN 检测", () => {
+    it("GITHUB_TOKEN + github.com 应识别为 github", () => {
+      const result = detectProvider({
+        GITHUB_TOKEN: "ghp-xxx",
+        GITHUB_SERVER_URL: "https://github.com",
+        GITHUB_API_URL: "https://api.github.com",
+      });
+      expect(result.provider).toBe("github");
+      expect(result.serverUrl).toBe("https://api.github.com");
+      expect(result.token).toBe("ghp-xxx");
+      expect(result.source).toContain("GITHUB_TOKEN");
+    });
+
+    it("GITHUB_TOKEN + 子域名也应识别为 github", () => {
+      const result = detectProvider({
+        GITHUB_TOKEN: "ghp-xxx",
+        GITHUB_SERVER_URL: "https://enterprise.github.com",
+      });
+      expect(result.provider).toBe("github");
+    });
+
+    it("GITHUB_TOKEN + 自定义域名也应识别为 github", () => {
+      const result = detectProvider({
+        GITHUB_TOKEN: "tok",
+        GITHUB_SERVER_URL: "https://git.example.com",
+      });
+      expect(result.provider).toBe("github");
+      expect(result.token).toBe("tok");
+      expect(result.source).toContain("GITHUB_TOKEN");
+    });
+
+    it("GITHUB_TOKEN 无 SERVER_URL 应识别为 github", () => {
+      const result = detectProvider({ GITHUB_TOKEN: "tok" });
+      expect(result.provider).toBe("github");
+      expect(result.source).toContain("GITHUB_TOKEN");
+    });
+  });
+
+  // ============ 默认 ============
+
+  describe("无任何环境变量", () => {
+    it("应默认为 github", () => {
+      const result = detectProvider({});
+      expect(result.provider).toBe("github");
+      expect(result.serverUrl).toBe("https://api.github.com");
+      expect(result.token).toBe("");
+      expect(result.source).toBe("默认");
+    });
+  });
+
+  // ============ GIT_PROVIDER_URL / GIT_PROVIDER_TOKEN 优先级 ============
+
+  describe("GIT_PROVIDER_URL / GIT_PROVIDER_TOKEN 优先级", () => {
+    it("GIT_PROVIDER_URL 应覆盖自动检测的 URL", () => {
+      const result = detectProvider({
+        GITEA_TOKEN: "tok",
+        GITEA_SERVER_URL: "https://gitea.example.com",
+        GIT_PROVIDER_URL: "https://custom.example.com",
+      });
+      expect(result.serverUrl).toBe("https://custom.example.com");
+    });
+
+    it("GIT_PROVIDER_TOKEN 应覆盖自动检测的 token", () => {
+      const result = detectProvider({
+        GITEA_TOKEN: "gitea-tok",
+        GIT_PROVIDER_TOKEN: "custom-tok",
+      });
+      expect(result.token).toBe("custom-tok");
+    });
+  });
+
+  // ============ GitHub 默认 API URL ============
+
+  describe("GitHub 默认 API URL", () => {
+    it("未指定 GITHUB_API_URL 时应使用默认值", () => {
+      const result = detectProvider({
+        GIT_PROVIDER_TYPE: "github",
+        GITHUB_TOKEN: "ghp-xxx",
+      });
+      expect(result.serverUrl).toBe("https://api.github.com");
+    });
+  });
+
+  // ============ Gitea Actions 场景（显式指定 GIT_PROVIDER_TYPE） ============
+
+  describe("Gitea Actions 场景", () => {
+    it("显式指定 gitea 时应回退到 GITHUB_SERVER_URL", () => {
+      const result = detectProvider({
+        GIT_PROVIDER_TYPE: "gitea",
+        GITHUB_TOKEN: "tok",
+        GITHUB_SERVER_URL: "https://git.bjxgj.com",
+      });
+      expect(result.provider).toBe("gitea");
+      expect(result.serverUrl).toBe("https://git.bjxgj.com");
+    });
+  });
+});

package/src/shared/git-provider/detect-provider.ts

@@ -0,0 +1,112 @@
+import type { GitProviderType } from "./types";
+
+/** 环境检测结果 */
+export interface DetectedProviderInfo {
+  /** 检测到的 provider 类型 */
+  provider: GitProviderType;
+  /** 检测到的服务器 URL */
+  serverUrl: string;
+  /** 检测到的 API Token */
+  token: string;
+  /** 检测来源说明 */
+  source: string;
+}
+
+/**
+ * 从环境变量自动检测 Git Provider 类型和配置
+ *
+ * 检测优先级：
+ * 1. 显式指定 `GIT_PROVIDER_TYPE` 环境变量（最高优先级）
+ * 2. 存在 `GITEA_TOKEN` → Gitea
+ * 3. 存在 `GITLAB_TOKEN` 或 `CI_JOB_TOKEN`（GitLab CI）→ GitLab
+ * 4. 存在 `GITHUB_TOKEN` → GitHub
+ * 5. 默认 → GitHub
+ */
+export function detectProvider(
+  env: Record<string, string | undefined> = process.env,
+): DetectedProviderInfo {
+  const explicit = env.GIT_PROVIDER_TYPE as GitProviderType | undefined;
+  if (explicit && isValidProvider(explicit)) {
+    return buildResult(explicit, env, "GIT_PROVIDER_TYPE 环境变量");
+  }
+  if (env.GITEA_TOKEN) {
+    return buildResult("gitea", env, "检测到 GITEA_TOKEN");
+  }
+  if (env.GITLAB_TOKEN || env.CI_JOB_TOKEN) {
+    return buildResult(
+      "gitlab",
+      env,
+      env.GITLAB_TOKEN ? "检测到 GITLAB_TOKEN" : "检测到 CI_JOB_TOKEN（GitLab CI）",
+    );
+  }
+  if (env.GITHUB_TOKEN) {
+    return buildResult("github", env, "检测到 GITHUB_TOKEN");
+  }
+  return buildResult("github", env, "默认");
+}
+
+/** 检查是否为有效的 provider 类型 */
+function isValidProvider(value: string): value is GitProviderType {
+  return value === "gitea" || value === "github" || value === "gitlab";
+}
+
+/** 根据 provider 类型从环境变量中提取 serverUrl 和 token */
+function buildResult(
+  provider: GitProviderType,
+  env: Record<string, string | undefined>,
+  source: string,
+): DetectedProviderInfo {
+  const serverUrl = resolveServerUrl(provider, env);
+  const token = resolveToken(provider, env);
+  return { provider, serverUrl, token, source };
+}
+
+/**
+ * 解析服务器 URL
+ * - 优先使用 GIT_PROVIDER_URL
+ * - Gitea: GITEA_SERVER_URL > GITHUB_SERVER_URL
+ * - GitHub: GITHUB_API_URL > 默认 https://api.github.com
+ * - GitLab: CI_SERVER_URL > GITLAB_URL
+ */
+function resolveServerUrl(
+  provider: GitProviderType,
+  env: Record<string, string | undefined>,
+): string {
+  if (env.GIT_PROVIDER_URL) {
+    return env.GIT_PROVIDER_URL;
+  }
+  if (provider === "github") {
+    return env.GITHUB_API_URL || "https://api.github.com";
+  }
+  if (provider === "gitlab") {
+    return env.CI_SERVER_URL || env.GITLAB_URL || "https://gitlab.com";
+  }
+  // Gitea: 优先 GITEA_SERVER_URL，其次从 GITHUB_SERVER_URL 推导
+  if (env.GITEA_SERVER_URL) {
+    return env.GITEA_SERVER_URL;
+  }
+  if (env.GITHUB_SERVER_URL) {
+    return env.GITHUB_SERVER_URL;
+  }
+  return "";
+}
+
+/**
+ * 解析 API Token
+ * - 优先使用 GIT_PROVIDER_TOKEN
+ * - Gitea: GITEA_TOKEN > GITHUB_TOKEN
+ * - GitHub: GITHUB_TOKEN
+ * - GitLab: GITLAB_TOKEN > CI_JOB_TOKEN
+ */
+function resolveToken(provider: GitProviderType, env: Record<string, string | undefined>): string {
+  if (env.GIT_PROVIDER_TOKEN) {
+    return env.GIT_PROVIDER_TOKEN;
+  }
+  if (provider === "github") {
+    return env.GITHUB_TOKEN || "";
+  }
+  if (provider === "gitlab") {
+    return env.GITLAB_TOKEN || env.CI_JOB_TOKEN || "";
+  }
+  return env.GITEA_TOKEN || env.GITHUB_TOKEN || "";
+}

package/src/shared/git-provider/git-provider.interface.ts

@@ -0,0 +1,188 @@
+import type {
+  BranchProtection,
+  CreateBranchProtectionOption,
+  EditBranchProtectionOption,
+  Branch,
+  Repository,
+  PullRequest,
+  PullRequestCommit,
+  ChangedFile,
+  CommitInfo,
+  IssueComment,
+  CreateIssueCommentOption,
+  CreateIssueOption,
+  Issue,
+  CreatePullReviewOption,
+  PullReview,
+  PullReviewComment,
+  Reaction,
+  EditPullRequestOption,
+  User,
+  RepositoryContent,
+} from "./types";
+
+/** PR 列表查询选项 */
+export interface ListPullRequestsOptions {
+  state?: "open" | "closed" | "all";
+  sort?: "oldest" | "recentupdate" | "leastupdate" | "mostcomment" | "leastcomment" | "priority";
+  milestone?: number;
+  labels?: string[];
+}
+
+/** 锁定分支选项 */
+export interface LockBranchOptions {
+  /** 允许推送的用户名白名单（如 CI 机器人） */
+  pushWhitelistUsernames?: string[];
+}
+
+/**
+ * Git Provider 抽象接口
+ * 定义所有 Git 托管平台需要实现的通用操作
+ */
+export interface GitProvider {
+  // ============ 配置验证 ============
+  /** 验证配置是否完整 */
+  validateConfig(): void;
+
+  // ============ 仓库操作 ============
+  /** 获取仓库信息 */
+  getRepository(owner: string, repo: string): Promise<Repository>;
+
+  // ============ 分支操作 ============
+  /** 获取分支信息 */
+  getBranch(owner: string, repo: string, branch: string): Promise<Branch>;
+
+  // ============ 分支保护 ============
+  /** 列出仓库的所有分支保护规则 */
+  listBranchProtections(owner: string, repo: string): Promise<BranchProtection[]>;
+  /** 获取特定分支保护规则 */
+  getBranchProtection(owner: string, repo: string, name: string): Promise<BranchProtection>;
+  /** 创建分支保护规则 */
+  createBranchProtection(
+    owner: string,
+    repo: string,
+    options: CreateBranchProtectionOption,
+  ): Promise<BranchProtection>;
+  /** 编辑分支保护规则 */
+  editBranchProtection(
+    owner: string,
+    repo: string,
+    name: string,
+    options: EditBranchProtectionOption,
+  ): Promise<BranchProtection>;
+  /** 删除分支保护规则 */
+  deleteBranchProtection(owner: string, repo: string, name: string): Promise<void>;
+  /** 锁定分支 - 禁止推送（可配置白名单用户） */
+  lockBranch(
+    owner: string,
+    repo: string,
+    branch: string,
+    options?: LockBranchOptions,
+  ): Promise<BranchProtection>;
+  /** 解锁分支 - 允许推送 */
+  unlockBranch(owner: string, repo: string, branch: string): Promise<BranchProtection | null>;
+  /** 同步解锁分支（用于进程退出时的清理） */
+  unlockBranchSync(owner: string, repo: string, branch: string): void;
+
+  // ============ Pull Request 操作 ============
+  /** 获取 Pull Request 信息 */
+  getPullRequest(owner: string, repo: string, index: number): Promise<PullRequest>;
+  /** 编辑 Pull Request */
+  editPullRequest(
+    owner: string,
+    repo: string,
+    index: number,
+    options: EditPullRequestOption,
+  ): Promise<PullRequest>;
+  /** 列出仓库的 Pull Request */
+  listPullRequests(
+    owner: string,
+    repo: string,
+    state?: "open" | "closed" | "all",
+  ): Promise<PullRequest[]>;
+  /** 列出仓库的所有 Pull Request（支持分页获取全部） */
+  listAllPullRequests(
+    owner: string,
+    repo: string,
+    options?: ListPullRequestsOptions,
+  ): Promise<PullRequest[]>;
+  /** 获取 PR 的 commits */
+  getPullRequestCommits(owner: string, repo: string, index: number): Promise<PullRequestCommit[]>;
+  /** 获取 PR 的文件变更 */
+  getPullRequestFiles(owner: string, repo: string, index: number): Promise<ChangedFile[]>;
+  /** 获取 PR 的 diff */
+  getPullRequestDiff(owner: string, repo: string, index: number): Promise<string>;
+
+  // ============ Commit 操作 ============
+  /** 获取单个 commit 信息 */
+  getCommit(owner: string, repo: string, sha: string): Promise<CommitInfo>;
+  /** 获取两个 ref 之间的 diff */
+  getCompareDiff(owner: string, repo: string, baseSha: string, headSha: string): Promise<string>;
+  /** 获取单个 commit 的 diff */
+  getCommitDiff(owner: string, repo: string, sha: string): Promise<string>;
+
+  // ============ 文件操作 ============
+  /** 获取文件内容 */
+  getFileContent(owner: string, repo: string, filepath: string, ref?: string): Promise<string>;
+  /** 列出仓库目录下的文件和子目录 */
+  listRepositoryContents(
+    owner: string,
+    repo: string,
+    path?: string,
+    ref?: string,
+  ): Promise<RepositoryContent[]>;
+
+  // ============ Issue 操作 ============
+  /** 创建 Issue */
+  createIssue(owner: string, repo: string, options: CreateIssueOption): Promise<Issue>;
+  /** 列出 Issue/PR 的评论 */
+  listIssueComments(owner: string, repo: string, index: number): Promise<IssueComment[]>;
+  /** 创建 Issue/PR 评论 */
+  createIssueComment(
+    owner: string,
+    repo: string,
+    index: number,
+    options: CreateIssueCommentOption,
+  ): Promise<IssueComment>;
+  /** 更新 Issue/PR 评论 */
+  updateIssueComment(
+    owner: string,
+    repo: string,
+    commentId: number,
+    body: string,
+  ): Promise<IssueComment>;
+  /** 删除 Issue/PR 评论 */
+  deleteIssueComment(owner: string, repo: string, commentId: number): Promise<void>;
+
+  // ============ PR Review 操作 ============
+  /** 创建 PR Review */
+  createPullReview(
+    owner: string,
+    repo: string,
+    index: number,
+    options: CreatePullReviewOption,
+  ): Promise<PullReview>;
+  /** 列出 PR 的所有 Reviews */
+  listPullReviews(owner: string, repo: string, index: number): Promise<PullReview[]>;
+  /** 删除 PR Review */
+  deletePullReview(owner: string, repo: string, index: number, reviewId: number): Promise<void>;
+  /** 获取 PR Review 的行级评论列表 */
+  listPullReviewComments(
+    owner: string,
+    repo: string,
+    index: number,
+    reviewId: number,
+  ): Promise<PullReviewComment[]>;
+
+  // ============ Reaction 操作 ============
+  /** 获取 Issue/PR 评论的 reactions */
+  getIssueCommentReactions(owner: string, repo: string, commentId: number): Promise<Reaction[]>;
+  /** 获取 Issue/PR 的 reactions */
+  getIssueReactions(owner: string, repo: string, index: number): Promise<Reaction[]>;
+
+  // ============ 用户操作 ============
+  /** 搜索用户 */
+  searchUsers(query: string, limit?: number): Promise<User[]>;
+  /** 获取团队成员列表 */
+  getTeamMembers(teamId: number): Promise<User[]>;
+}

package/src/shared/git-provider/git-provider.module.ts

@@ -0,0 +1,73 @@
+import { DynamicModule, Module } from "@nestjs/common";
+import { ConfigModule, ConfigService } from "@nestjs/config";
+import { GitProviderService } from "./git-provider.service";
+import {
+  type GitProviderModuleOptions,
+  type GitProviderModuleAsyncOptions,
+  GIT_PROVIDER_MODULE_OPTIONS,
+} from "./types";
+import { gitProviderConfig, type GitProviderConfig } from "../../config/git-provider.config";
+
+@Module({})
+export class GitProviderModule {
+  /**
+   * 同步注册模块
+   */
+  static forRoot(options: GitProviderModuleOptions): DynamicModule {
+    return {
+      module: GitProviderModule,
+      providers: [
+        {
+          provide: GIT_PROVIDER_MODULE_OPTIONS,
+          useValue: options,
+        },
+        GitProviderService,
+      ],
+      exports: [GitProviderService],
+    };
+  }
+
+  /**
+   * 异步注册模块 - 支持从环境变量等动态获取配置
+   */
+  static forRootAsync(options: GitProviderModuleAsyncOptions): DynamicModule {
+    return {
+      module: GitProviderModule,
+      providers: [
+        {
+          provide: GIT_PROVIDER_MODULE_OPTIONS,
+          useFactory: options.useFactory,
+          inject: options.inject || [],
+        },
+        GitProviderService,
+      ],
+      exports: [GitProviderService],
+    };
+  }
+
+  /**
+   * 使用 ConfigService 注册模块
+   */
+  static forFeature(): DynamicModule {
+    return {
+      module: GitProviderModule,
+      imports: [ConfigModule.forFeature(gitProviderConfig)],
+      providers: [
+        {
+          provide: GIT_PROVIDER_MODULE_OPTIONS,
+          useFactory: (configService: ConfigService): GitProviderModuleOptions => {
+            const config = configService.get<GitProviderConfig>("gitProvider");
+            return {
+              provider: config?.provider || "gitea",
+              baseUrl: config?.serverUrl || "",
+              token: config?.token || "",
+            };
+          },
+          inject: [ConfigService],
+        },
+        GitProviderService,
+      ],
+      exports: [GitProviderService],
+    };
+  }
+}