@shipfox/api-integration-gitea 2.0.0

package/src/core/source-control-clone-url.test.ts

@@ -0,0 +1,83 @@
+import type {IntegrationConnection} from '@shipfox/api-integration-core-dto';
+import type {GiteaApiClient, GiteaRepository} from '#api/client.js';
+
+const REPOSITORY: GiteaRepository = {
+  ownerLogin: 'shipfox',
+  name: 'platform',
+  fullName: 'shipfox/platform',
+  defaultBranch: 'main',
+  private: true,
+  cloneUrl: 'https://gitea.example.com/shipfox/platform.git',
+  htmlUrl: 'https://gitea.example.com/shipfox/platform',
+};
+
+function giteaClient(repository: GiteaRepository): GiteaApiClient {
+  return {
+    listOrgRepositories: vi.fn(),
+    getRepository: vi.fn(() => Promise.resolve(repository)),
+    resolveRef: vi.fn(),
+    listTree: vi.fn(),
+    fetchFileContent: vi.fn(),
+    organizationExists: vi.fn(),
+  };
+}
+
+function connection(): IntegrationConnection<'gitea'> {
+  return {
+    id: crypto.randomUUID(),
+    workspaceId: crypto.randomUUID(),
+    provider: 'gitea',
+    externalAccountId: 'shipfox',
+    slug: 'gitea_shipfox',
+    displayName: 'Gitea shipfox',
+    lifecycleStatus: 'active',
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+}
+
+async function createCheckoutSpec(repository: GiteaRepository) {
+  const {GiteaSourceControlProvider} = await import('./source-control.js');
+  const provider = new GiteaSourceControlProvider(giteaClient(repository));
+
+  return provider.createCheckoutSpec({
+    connection: connection(),
+    externalRepositoryId: 'gitea:shipfox/platform',
+  });
+}
+
+describe('GiteaSourceControlProvider clone URL override', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.resetModules();
+  });
+
+  it('uses the provider clone URL when GITEA_CLONE_BASE_URL is unset', async () => {
+    vi.resetModules();
+
+    const result = await createCheckoutSpec(REPOSITORY);
+
+    expect(result.repositoryUrl).toBe('https://gitea.example.com/shipfox/platform.git');
+  });
+
+  it('replaces the checkout clone URL origin when GITEA_CLONE_BASE_URL is set', async () => {
+    vi.stubEnv('GITEA_CLONE_BASE_URL', 'http://gitea:3000');
+    vi.resetModules();
+
+    const result = await createCheckoutSpec(REPOSITORY);
+
+    expect(result.repositoryUrl).toBe('http://gitea:3000/shipfox/platform.git');
+  });
+
+  it('keeps a non-root repository path prefix from the provider clone URL', async () => {
+    vi.stubEnv('GITEA_CLONE_BASE_URL', 'http://gitea:3000');
+    vi.resetModules();
+
+    const result = await createCheckoutSpec({
+      ...REPOSITORY,
+      cloneUrl: 'https://gitea.example.com/git/shipfox/platform.git',
+    });
+
+    expect(result.repositoryUrl).toBe('http://gitea:3000/git/shipfox/platform.git');
+  });
+});

package/src/core/source-control.test.ts

@@ -0,0 +1,349 @@
+import type {IntegrationConnection} from '@shipfox/api-integration-core-dto';
+import type {GiteaApiClient, GiteaRepository} from '#api/client.js';
+import {GiteaIntegrationProviderError} from './errors.js';
+import {GiteaSourceControlProvider} from './source-control.js';
+
+const REPOSITORY: GiteaRepository = {
+  ownerLogin: 'shipfox',
+  name: 'platform',
+  fullName: 'shipfox/platform',
+  defaultBranch: 'main',
+  private: true,
+  cloneUrl: 'https://gitea.example.com/shipfox/platform.git',
+  htmlUrl: 'https://gitea.example.com/shipfox/platform',
+};
+
+function giteaClient(overrides: Partial<GiteaApiClient> = {}): GiteaApiClient {
+  return {
+    listOrgRepositories: vi.fn(() =>
+      Promise.resolve({repositories: [REPOSITORY], nextCursor: '2'}),
+    ),
+    getRepository: vi.fn(() => Promise.resolve(REPOSITORY)),
+    resolveRef: vi.fn(() => Promise.resolve('abc123')),
+    listTree: vi.fn(() =>
+      Promise.resolve({
+        blobs: [{path: '.shipfox/workflows/ci.yml', size: 64}],
+        truncated: false,
+      }),
+    ),
+    fetchFileContent: vi.fn(() =>
+      Promise.resolve({
+        path: '.shipfox/workflows/ci.yml',
+        content: 'name: CI\njobs:\n  build:\n    steps:\n      - run: pnpm test\n',
+        size: 58,
+      }),
+    ),
+    organizationExists: vi.fn(() => Promise.resolve(true)),
+    ...overrides,
+  };
+}
+
+function connection(): IntegrationConnection<'gitea'> {
+  return {
+    id: crypto.randomUUID(),
+    workspaceId: crypto.randomUUID(),
+    provider: 'gitea',
+    externalAccountId: 'shipfox',
+    slug: 'gitea_shipfox',
+    displayName: 'Gitea shipfox',
+    lifecycleStatus: 'active',
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+}
+
+describe('GiteaSourceControlProvider', () => {
+  it('lists org repositories scoped to the connection account', async () => {
+    const gitea = giteaClient();
+    const provider = new GiteaSourceControlProvider(gitea);
+
+    const result = await provider.listRepositories({connection: connection(), limit: 50});
+
+    expect(result.repositories[0]?.externalRepositoryId).toBe('gitea:shipfox/platform');
+    expect(result.repositories[0]?.visibility).toBe('private');
+    expect(result.nextCursor).toBe('2');
+    expect(gitea.listOrgRepositories).toHaveBeenCalledWith({
+      org: 'shipfox',
+      limit: 50,
+      cursor: undefined,
+    });
+  });
+
+  it('filters repositories by search across scanned pages', async () => {
+    const gitea = giteaClient({
+      listOrgRepositories: vi.fn(() =>
+        Promise.resolve({
+          repositories: [REPOSITORY, {...REPOSITORY, name: 'docs', fullName: 'shipfox/docs'}],
+          nextCursor: null,
+        }),
+      ),
+    });
+    const provider = new GiteaSourceControlProvider(gitea);
+
+    const result = await provider.listRepositories({
+      connection: connection(),
+      limit: 50,
+      search: 'docs',
+    });
+
+    expect(result.repositories.map((repo) => repo.fullName)).toEqual(['shipfox/docs']);
+  });
+
+  it('resolves a repository from the provider-owned id', async () => {
+    const gitea = giteaClient();
+    const provider = new GiteaSourceControlProvider(gitea);
+
+    const result = await provider.resolveRepository({
+      connection: connection(),
+      externalRepositoryId: 'gitea:shipfox/platform',
+    });
+
+    expect(result.fullName).toBe('shipfox/platform');
+    expect(gitea.getRepository).toHaveBeenCalledWith({owner: 'shipfox', repo: 'platform'});
+  });
+
+  it('lists files under a prefix from the recursive tree', async () => {
+    const gitea = giteaClient({
+      listTree: vi.fn(() =>
+        Promise.resolve({
+          blobs: [
+            {path: 'README.md', size: 10},
+            {path: '.shipfox/workflows/ci.yml', size: 64},
+            {path: '.shipfox/workflows/release.yml', size: 80},
+          ],
+          truncated: false,
+        }),
+      ),
+    });
+    const provider = new GiteaSourceControlProvider(gitea);
+
+    const result = await provider.listFiles({
+      connection: connection(),
+      externalRepositoryId: 'gitea:shipfox/platform',
+      ref: 'main',
+      prefix: '.shipfox/workflows/',
+      limit: 100,
+    });
+
+    expect(result.files.map((file) => file.path)).toEqual([
+      '.shipfox/workflows/ci.yml',
+      '.shipfox/workflows/release.yml',
+    ]);
+    expect(result.files[0]).toEqual({path: '.shipfox/workflows/ci.yml', type: 'file', size: 64});
+    expect(gitea.resolveRef).toHaveBeenCalledWith({
+      owner: 'shipfox',
+      repo: 'platform',
+      ref: 'main',
+    });
+    expect(gitea.listTree).toHaveBeenCalledWith({
+      owner: 'shipfox',
+      repo: 'platform',
+      sha: 'abc123',
+    });
+  });
+
+  it('paginates files with an offset cursor', async () => {
+    const gitea = giteaClient({
+      listTree: vi.fn(() =>
+        Promise.resolve({
+          blobs: [
+            {path: 'a.txt', size: 1},
+            {path: 'b.txt', size: 1},
+            {path: 'c.txt', size: 1},
+          ],
+          truncated: false,
+        }),
+      ),
+    });
+    const provider = new GiteaSourceControlProvider(gitea);
+
+    const firstPage = await provider.listFiles({
+      connection: connection(),
+      externalRepositoryId: 'gitea:shipfox/platform',
+      ref: 'main',
+      prefix: '',
+      limit: 2,
+    });
+
+    expect(firstPage.files.map((file) => file.path)).toEqual(['a.txt', 'b.txt']);
+    expect(firstPage.nextCursor).toBe('2');
+
+    const secondPage = await provider.listFiles({
+      connection: connection(),
+      externalRepositoryId: 'gitea:shipfox/platform',
+      ref: 'main',
+      prefix: '',
+      limit: 2,
+      cursor: firstPage.nextCursor ?? undefined,
+    });
+
+    expect(secondPage.files.map((file) => file.path)).toEqual(['c.txt']);
+    expect(secondPage.nextCursor).toBeNull();
+  });
+
+  it('rejects listing files when the tree is truncated', async () => {
+    const gitea = giteaClient({
+      listTree: vi.fn(() => Promise.resolve({blobs: [], truncated: true})),
+    });
+    const provider = new GiteaSourceControlProvider(gitea);
+
+    const result = provider.listFiles({
+      connection: connection(),
+      externalRepositoryId: 'gitea:shipfox/platform',
+      ref: 'main',
+      prefix: '',
+      limit: 100,
+    });
+
+    await expect(result).rejects.toMatchObject({reason: 'too-many-files'});
+  });
+
+  it('fetches file content from the provider-owned id', async () => {
+    const gitea = giteaClient();
+    const provider = new GiteaSourceControlProvider(gitea);
+
+    const result = await provider.fetchFile({
+      connection: connection(),
+      externalRepositoryId: 'gitea:shipfox/platform',
+      ref: 'main',
+      path: '.shipfox/workflows/ci.yml',
+    });
+
+    expect(result.content).toContain('name: CI');
+    expect(result.ref).toBe('main');
+    expect(gitea.fetchFileContent).toHaveBeenCalledWith({
+      owner: 'shipfox',
+      repo: 'platform',
+      path: '.shipfox/workflows/ci.yml',
+      ref: 'main',
+    });
+  });
+
+  it('rejects oversized file content', async () => {
+    const gitea = giteaClient({
+      fetchFileContent: vi.fn(() =>
+        Promise.resolve({path: 'big.bin', content: 'x'.repeat(1_000_001), size: 1_000_001}),
+      ),
+    });
+    const provider = new GiteaSourceControlProvider(gitea);
+
+    const result = provider.fetchFile({
+      connection: connection(),
+      externalRepositoryId: 'gitea:shipfox/platform',
+      ref: 'main',
+      path: 'big.bin',
+    });
+
+    await expect(result).rejects.toMatchObject({reason: 'content-too-large'});
+  });
+
+  it.each([
+    'shipfox/platform',
+    'gitea:',
+    'gitea:platform',
+    'gitea:shipfox/',
+    'gitea:/platform',
+    'gitea:shipfox/platform/extra',
+    'github:shipfox/platform',
+    '',
+  ])('rejects the malformed external repository id %s before any api call', async (id) => {
+    const gitea = giteaClient();
+    const provider = new GiteaSourceControlProvider(gitea);
+
+    const result = provider.resolveRepository({connection: connection(), externalRepositoryId: id});
+
+    await expect(result).rejects.toMatchObject({reason: 'repository-not-found'});
+    expect(gitea.getRepository).not.toHaveBeenCalled();
+  });
+
+  it('rejects an external repository id outside the connection account before any api call', async () => {
+    const gitea = giteaClient();
+    const provider = new GiteaSourceControlProvider(gitea);
+
+    const result = provider.resolveRepository({
+      connection: connection(),
+      externalRepositoryId: 'gitea:intruder/platform',
+    });
+
+    await expect(result).rejects.toMatchObject({reason: 'repository-not-found'});
+    expect(gitea.getRepository).not.toHaveBeenCalled();
+  });
+
+  it('creates a credential-free checkout spec carrying the service credentials', async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-06-20T00:00:00.000Z'));
+    try {
+      const gitea = giteaClient();
+      const provider = new GiteaSourceControlProvider(gitea);
+
+      const result = await provider.createCheckoutSpec({
+        connection: connection(),
+        externalRepositoryId: 'gitea:shipfox/platform',
+        ref: 'feature/x',
+      });
+
+      expect(result).toEqual({
+        repositoryUrl: 'https://gitea.example.com/shipfox/platform.git',
+        ref: 'feature/x',
+        credentials: {
+          username: 'shipfox-bot',
+          token: 'test-service-token',
+          expiresAt: new Date('2026-06-20T00:05:00.000Z'),
+        },
+      });
+      const url = new URL(result.repositoryUrl);
+      expect(url.username).toBe('');
+      expect(url.password).toBe('');
+      expect(result.repositoryUrl).not.toContain('test-service-token');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('defaults the checkout ref to the repository default branch', async () => {
+    const gitea = giteaClient();
+    const provider = new GiteaSourceControlProvider(gitea);
+
+    const result = await provider.createCheckoutSpec({
+      connection: connection(),
+      externalRepositoryId: 'gitea:shipfox/platform',
+    });
+
+    expect(result.ref).toBe('main');
+  });
+
+  it('builds the checkout url from the provider clone url, not the configured base url', async () => {
+    const gitea = giteaClient({
+      getRepository: vi.fn(() =>
+        Promise.resolve({
+          ...REPOSITORY,
+          cloneUrl: 'https://git.internal.example/shipfox/platform.git',
+        }),
+      ),
+    });
+    const provider = new GiteaSourceControlProvider(gitea);
+
+    const result = await provider.createCheckoutSpec({
+      connection: connection(),
+      externalRepositoryId: 'gitea:shipfox/platform',
+    });
+
+    expect(result.repositoryUrl).toBe('https://git.internal.example/shipfox/platform.git');
+  });
+
+  it('propagates provider errors raised while reading the repository', async () => {
+    const gitea = giteaClient({
+      getRepository: vi.fn(() =>
+        Promise.reject(new GiteaIntegrationProviderError('access-denied', 'denied')),
+      ),
+    });
+    const provider = new GiteaSourceControlProvider(gitea);
+
+    const result = provider.createCheckoutSpec({
+      connection: connection(),
+      externalRepositoryId: 'gitea:shipfox/platform',
+    });
+
+    await expect(result).rejects.toMatchObject({reason: 'access-denied'});
+  });
+});

package/src/core/source-control.ts

@@ -0,0 +1,231 @@
+import {Buffer} from 'node:buffer';
+import {
+  buildProviderRepositoryId,
+  type CheckoutSpec,
+  type CreateCheckoutSpecInput,
+  type FetchFileInput,
+  type FilePage,
+  type FileSnapshot,
+  type IntegrationConnection,
+  type ListFilesInput,
+  type ListRepositoriesInput,
+  MAX_REPOSITORY_FILE_BYTES,
+  parseProviderRepositoryId,
+  type RepositoryPage,
+  type RepositorySnapshot,
+  type RepositoryVisibility,
+  type ResolveRepositoryInput,
+  type SourceControlProvider,
+} from '@shipfox/api-integration-core-dto';
+import {giteaProviderKind} from '@shipfox/api-integration-gitea-dto';
+import type {GiteaApiClient, GiteaRepository} from '#api/client.js';
+import {config, giteaCloneBaseOrigin} from '#config.js';
+import {GiteaIntegrationProviderError} from './errors.js';
+
+type GiteaIntegrationConnection = IntegrationConnection<'gitea'>;
+
+const TRAILING_SLASHES_RE = /\/+$/;
+const SEARCH_PAGE_SIZE = 100;
+const SEARCH_MAX_PAGES_PER_REQUEST = 5;
+
+export class GiteaSourceControlProvider
+  implements SourceControlProvider<GiteaIntegrationConnection>
+{
+  constructor(private readonly gitea: GiteaApiClient) {}
+
+  async listRepositories(
+    input: ListRepositoriesInput<GiteaIntegrationConnection>,
+  ): Promise<RepositoryPage> {
+    const org = input.connection.externalAccountId;
+    const needle = input.search?.trim().toLowerCase();
+
+    if (!needle) {
+      const page = await this.gitea.listOrgRepositories({
+        org,
+        limit: input.limit,
+        cursor: input.cursor,
+      });
+      return {
+        repositories: page.repositories.map(toRepositorySnapshot),
+        nextCursor: page.nextCursor,
+      };
+    }
+
+    const matches: RepositorySnapshot[] = [];
+    let cursor = input.cursor;
+    let pagesScanned = 0;
+    while (matches.length < input.limit && pagesScanned < SEARCH_MAX_PAGES_PER_REQUEST) {
+      const page = await this.gitea.listOrgRepositories({org, limit: SEARCH_PAGE_SIZE, cursor});
+      pagesScanned += 1;
+      for (const repo of page.repositories) {
+        if (repo.fullName.toLowerCase().includes(needle)) {
+          matches.push(toRepositorySnapshot(repo));
+        }
+      }
+      cursor = page.nextCursor ?? undefined;
+      if (!cursor) break;
+    }
+
+    return {
+      repositories: matches.slice(0, input.limit),
+      nextCursor: cursor ?? null,
+    };
+  }
+
+  async resolveRepository(
+    input: ResolveRepositoryInput<GiteaIntegrationConnection>,
+  ): Promise<RepositorySnapshot> {
+    const {owner, repo} = parseGiteaRepositoryLocator(
+      input.externalRepositoryId,
+      input.connection.externalAccountId,
+    );
+    return toRepositorySnapshot(await this.gitea.getRepository({owner, repo}));
+  }
+
+  async listFiles(input: ListFilesInput<GiteaIntegrationConnection>): Promise<FilePage> {
+    const {owner, repo} = parseGiteaRepositoryLocator(
+      input.externalRepositoryId,
+      input.connection.externalAccountId,
+    );
+    const sha = await this.gitea.resolveRef({owner, repo, ref: input.ref});
+    const tree = await this.gitea.listTree({owner, repo, sha});
+    if (tree.truncated) {
+      throw new GiteaIntegrationProviderError(
+        'too-many-files',
+        `Gitea repository tree for ${input.externalRepositoryId} is too large to enumerate`,
+      );
+    }
+
+    const prefix = input.prefix.replace(TRAILING_SLASHES_RE, '');
+    const matched = tree.blobs
+      .filter((blob) => prefixMatches(blob.path, prefix))
+      .sort((a, b) => a.path.localeCompare(b.path));
+    const offset = parseOffset(input.cursor);
+    const page = matched.slice(offset, offset + input.limit);
+    const consumed = offset + page.length;
+
+    return {
+      files: page.map((blob) => ({path: blob.path, type: 'file', size: blob.size})),
+      nextCursor: consumed < matched.length ? String(consumed) : null,
+    };
+  }
+
+  async fetchFile(input: FetchFileInput<GiteaIntegrationConnection>): Promise<FileSnapshot> {
+    const {owner, repo} = parseGiteaRepositoryLocator(
+      input.externalRepositoryId,
+      input.connection.externalAccountId,
+    );
+    const file = await this.gitea.fetchFileContent({owner, repo, path: input.path, ref: input.ref});
+
+    if (
+      file.size > MAX_REPOSITORY_FILE_BYTES ||
+      Buffer.byteLength(file.content, 'utf8') > MAX_REPOSITORY_FILE_BYTES
+    ) {
+      throw new GiteaIntegrationProviderError(
+        'content-too-large',
+        'Gitea file content is larger than the supported limit',
+      );
+    }
+
+    return {
+      path: file.path,
+      ref: input.ref,
+      content: file.content,
+    };
+  }
+
+  async createCheckoutSpec(
+    input: CreateCheckoutSpecInput<GiteaIntegrationConnection>,
+  ): Promise<CheckoutSpec> {
+    const {owner, repo} = parseGiteaRepositoryLocator(
+      input.externalRepositoryId,
+      input.connection.externalAccountId,
+    );
+    const repository = await this.gitea.getRepository({owner, repo});
+    const ref = input.ref?.trim() || repository.defaultBranch;
+
+    return {
+      repositoryUrl: createCheckoutRepositoryUrl(repository.cloneUrl),
+      ref,
+      // Gitea has no per-repo, auto-expiring token like a GitHub App installation
+      // token, so checkout reuses the long-lived service credential. `expiresAt`
+      // is the runner's lease/refresh window, not the token's real expiry: this
+      // credential does not actually expire and stays valid if it leaks.
+      credentials: {
+        username: config.GITEA_SERVICE_USERNAME,
+        token: config.GITEA_SERVICE_TOKEN,
+        expiresAt: new Date(Date.now() + config.GITEA_CHECKOUT_TTL_SECONDS * 1000),
+      },
+    };
+  }
+}
+
+function createCheckoutRepositoryUrl(cloneUrl: string): string {
+  if (!giteaCloneBaseOrigin) return cloneUrl;
+
+  const repositoryUrl = new URL(cloneUrl);
+
+  repositoryUrl.protocol = giteaCloneBaseOrigin.protocol;
+  repositoryUrl.host = giteaCloneBaseOrigin.host;
+
+  return repositoryUrl.toString();
+}
+
+function toRepositorySnapshot(repository: GiteaRepository): RepositorySnapshot {
+  return {
+    externalRepositoryId: buildProviderRepositoryId(
+      giteaProviderKind,
+      `${repository.ownerLogin}/${repository.name}`,
+    ),
+    owner: repository.ownerLogin,
+    name: repository.name,
+    fullName: repository.fullName,
+    defaultBranch: repository.defaultBranch,
+    visibility: toRepositoryVisibility(repository),
+    cloneUrl: repository.cloneUrl,
+    htmlUrl: repository.htmlUrl,
+  };
+}
+
+function toRepositoryVisibility(repository: GiteaRepository): RepositoryVisibility {
+  return repository.private ? 'private' : 'public';
+}
+
+function parseGiteaRepositoryLocator(
+  externalRepositoryId: string,
+  expectedOwner: string,
+): {owner: string; repo: string} {
+  const value = parseProviderRepositoryId(externalRepositoryId, giteaProviderKind);
+  const separatorIndex = value.indexOf('/');
+  const owner = separatorIndex > 0 ? value.slice(0, separatorIndex) : '';
+  const repo = separatorIndex > 0 ? value.slice(separatorIndex + 1) : '';
+  if (!owner || !repo || repo.includes('/')) {
+    throw new GiteaIntegrationProviderError(
+      'repository-not-found',
+      `Gitea repository id ${externalRepositoryId} must follow the form ${giteaProviderKind}:<owner>/<repo>`,
+    );
+  }
+  // The service token is instance-wide, so the adapter must scope every request
+  // to the connection's own account itself; without this an external id naming
+  // another org would read its private repos and mint checkout credentials for
+  // them. Reported as not-found so it does not confirm an out-of-scope repo.
+  if (owner.toLowerCase() !== expectedOwner.toLowerCase()) {
+    throw new GiteaIntegrationProviderError(
+      'repository-not-found',
+      `Gitea repository id ${externalRepositoryId} is not in the ${expectedOwner} account`,
+    );
+  }
+
+  return {owner, repo};
+}
+
+function prefixMatches(path: string, prefix: string): boolean {
+  if (!prefix) return true;
+  return path === prefix || path.startsWith(`${prefix}/`);
+}
+
+function parseOffset(cursor: string | undefined): number {
+  if (!cursor) return 0;
+  const offset = Number.parseInt(cursor, 10);
+  return Number.isNaN(offset) || offset < 0 ? 0 : offset;
+}