@shipfox/api-integration-github 13.1.0 → 14.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-integration-github",
   "license": "MIT",
-  "version": "13.1.0",
+  "version": "14.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -28,8 +28,8 @@
     "octokit": "^5.0.3",
     "zod": "^4.4.3",
     "@shipfox/api-auth-context": "12.2.0",
-    "@shipfox/api-integration-spi": "1.1.1",
-    "@shipfox/api-integration-github-dto": "12.2.0",
+    "@shipfox/api-integration-spi": "2.0.0",
+    "@shipfox/api-integration-github-dto": "14.0.0",
     "@shipfox/config": "1.2.4",
     "@shipfox/node-drizzle": "0.3.5",
     "@shipfox/node-fastify": "0.4.2",

package/src/api/client.test.ts

@@ -7,29 +7,40 @@ import {createGithubApiClient, mapGithubError} from './client.js';
 
 const GITHUB_INSTALLATION_TOKEN_PATTERN = /^ghs_[A-Za-z0-9._-]{36,}$/u;
 
-const {createInstallationAccessTokenMock, getByUsernameMock, octokitOptionsMock, RequestErrorMock} =
-  vi.hoisted(() => {
-    class RequestErrorMock extends Error {
-      constructor(
-        message: string,
-        public readonly status: number,
-      ) {
-        super(message);
-        this.name = 'HttpError';
-      }
+const {
+  authMock,
+  createInstallationAccessTokenMock,
+  getByUsernameMock,
+  listRepositoryCommitsMock,
+  octokitOptionsMock,
+  requestMock,
+  RequestErrorMock,
+} = vi.hoisted(() => {
+  class RequestErrorMock extends Error {
+    constructor(
+      message: string,
+      public readonly status: number,
+    ) {
+      super(message);
+      this.name = 'HttpError';
     }
-
-    return {
-      createInstallationAccessTokenMock: vi.fn(),
-      getByUsernameMock: vi.fn(),
-      octokitOptionsMock: vi.fn(),
-      RequestErrorMock,
-    };
-  });
+  }
+
+  return {
+    authMock: vi.fn(),
+    createInstallationAccessTokenMock: vi.fn(),
+    getByUsernameMock: vi.fn(),
+    listRepositoryCommitsMock: vi.fn(),
+    octokitOptionsMock: vi.fn(),
+    requestMock: vi.fn(),
+    RequestErrorMock,
+  };
+});
 
 vi.mock('octokit', () => ({
   App: class App {
     octokit = {
+      auth: authMock,
       rest: {
         apps: {createInstallationAccessToken: createInstallationAccessTokenMock},
         users: {getByUsername: getByUsernameMock},
@@ -37,7 +48,11 @@ vi.mock('octokit', () => ({
     };
   },
   Octokit: class Octokit {
-    rest = {users: {getByUsername: getByUsernameMock}};
+    rest = {
+      repos: {listCommits: listRepositoryCommitsMock},
+      users: {getByUsername: getByUsernameMock},
+    };
+    request = requestMock;
 
     constructor(options: unknown) {
       octokitOptionsMock(options);
@@ -252,6 +267,61 @@ describe('mapGithubError', () => {
   });
 });
 
+describe('OctokitGithubApiClient.listRepositoryCommits', () => {
+  beforeEach(() => {
+    authMock.mockReset();
+    listRepositoryCommitsMock.mockReset();
+    requestMock.mockReset();
+  });
+
+  it.each([
+    [404, 'repository-not-found'],
+    [409, 'ref-not-found'],
+    [422, 'ref-not-found'],
+  ] as const)('maps HTTP %i commit lookup failures to %s', async (status, reason) => {
+    authMock.mockResolvedValue({token: 'ghs_installationtoken'});
+    requestMock.mockResolvedValue({
+      data: {
+        id: 42,
+        owner: {login: 'shipfox'},
+        name: 'platform',
+        full_name: 'shipfox/platform',
+        default_branch: 'main',
+        private: true,
+        clone_url: 'https://github.com/shipfox/platform.git',
+        html_url: 'https://github.com/shipfox/platform',
+      },
+    });
+    listRepositoryCommitsMock.mockRejectedValue(
+      new RequestErrorMock('No commit found for SHA', status),
+    );
+    const client = createGithubApiClient();
+
+    const result = client.listRepositoryCommits({
+      installationId: 1,
+      repositoryId: 42,
+      ref: 'refs/heads/missing',
+    });
+
+    await expect(result).rejects.toMatchObject({
+      reason,
+      status,
+      message: 'No commit found for SHA',
+    });
+    expect(requestMock).toHaveBeenCalledWith('GET /repositories/{repository_id}', {
+      repository_id: 42,
+      request: {signal: expect.any(AbortSignal)},
+    });
+    expect(listRepositoryCommitsMock).toHaveBeenCalledWith({
+      owner: 'shipfox',
+      repo: 'platform',
+      sha: 'refs/heads/missing',
+      per_page: 1,
+      request: {signal: expect.any(AbortSignal)},
+    });
+  });
+});
+
 describe('OctokitGithubApiClient.createInstallationAccessToken', () => {
   beforeEach(() => {
     createInstallationAccessTokenMock.mockReset();

package/src/api/client.ts

@@ -63,6 +63,10 @@ export interface GithubFileContent {
   size: number;
 }
 
+export interface GithubCommit {
+  sha: string;
+}
+
 export interface GithubUserInstallationPage {
   installationIds: number[];
   nextCursor: string | null;
@@ -104,6 +108,11 @@ export interface GithubApiClient extends Partial<GithubBotUserClient> {
     ref: string;
     path: string;
   }): Promise<GithubFileContent>;
+  listRepositoryCommits(input: {
+    installationId: number;
+    repositoryId: number;
+    ref: string;
+  }): Promise<GithubCommit[]>;
   createInstallationAccessToken(input: {
     installationId: number;
     repositoryId: number;
@@ -267,6 +276,7 @@ class OctokitGithubApiClient implements GithubApiClient, GithubBotUserClient {
     const response = await mapGithubError(() =>
       octokit.request('GET /repositories/{repository_id}', {
         repository_id: input.repositoryId,
+        request: {signal: AbortSignal.timeout(GITHUB_API_TIMEOUT_MS)},
       }),
     );
 
@@ -405,6 +415,40 @@ class OctokitGithubApiClient implements GithubApiClient, GithubBotUserClient {
     };
   }
 
+  async listRepositoryCommits(input: {
+    installationId: number;
+    repositoryId: number;
+    ref: string;
+  }): Promise<GithubCommit[]> {
+    const octokit = await mapGithubError(() =>
+      getGithubInstallationOctokit(this.getApp(), input.installationId),
+    );
+    const repository = await this.getRepository({
+      installationId: input.installationId,
+      repositoryId: input.repositoryId,
+    });
+    const response = await mapGithubError(
+      () =>
+        octokit.rest.repos.listCommits({
+          owner: repository.ownerLogin,
+          repo: repository.name,
+          sha: input.ref,
+          per_page: 1,
+          request: {signal: AbortSignal.timeout(GITHUB_API_TIMEOUT_MS)},
+        }),
+      'ref-not-found',
+    );
+    return response.data.map((commit) => {
+      if (typeof commit.sha !== 'string') {
+        throw new GithubIntegrationProviderError(
+          'malformed-provider-response',
+          'GitHub commit response is missing the commit sha',
+        );
+      }
+      return {sha: commit.sha};
+    });
+  }
+
   async createInstallationAccessToken(input: {
     installationId: number;
     repositoryId: number;
@@ -558,6 +602,7 @@ export async function mapGithubError<T>(
     | 'repository-not-found'
     | 'installation-not-found'
     | 'file-not-found'
+    | 'ref-not-found'
     | 'provider-rejected' = 'repository-not-found',
 ): Promise<T> {
   try {
@@ -570,7 +615,15 @@ export async function mapGithubError<T>(
     if (error instanceof RequestError) {
       if (error.status === 404) {
         throw new GithubIntegrationProviderError(
-          notFoundReason,
+          notFoundReason === 'ref-not-found' ? 'repository-not-found' : notFoundReason,
+          error.message,
+          undefined,
+          error.status,
+        );
+      }
+      if (notFoundReason === 'ref-not-found' && (error.status === 409 || error.status === 422)) {
+        throw new GithubIntegrationProviderError(
+          'ref-not-found',
           error.message,
           undefined,
           error.status,

package/src/api/installation-token-envelope.ts

@@ -37,9 +37,11 @@ const terminalMintErrorReasons = new Set<IntegrationProviderErrorReason>([
   'malformed-provider-response',
 ]);
 
+// Ref reasons describe ref-resolution failures, which a token mint never
+// observes; keep them out of the envelope schema and acknowledge them here.
 type MissingProviderErrorReason = Exclude<
   IntegrationProviderErrorReason,
-  (typeof providerErrorReasons)[number]
+  (typeof providerErrorReasons)[number] | 'ref-not-found' | 'ref-invalid'
 >;
 const providerErrorReasonSchemaCoversUnion: Record<MissingProviderErrorReason, never> = {};
 void providerErrorReasonSchemaCoversUnion;

package/src/core/agent-tools.test.ts

@@ -1734,6 +1734,7 @@ function githubClient(): GithubApiClient {
     getRepository: vi.fn(() => Promise.reject(new Error('not used'))),
     listRepositoryFiles: vi.fn(() => Promise.reject(new Error('not used'))),
     fetchRepositoryFile: vi.fn(() => Promise.reject(new Error('not used'))),
+    listRepositoryCommits: vi.fn(() => Promise.reject(new Error('not used'))),
     createInstallationAccessToken: vi.fn(() => Promise.reject(new Error('not used'))),
   };
 }

package/src/core/install.test.ts

@@ -37,6 +37,9 @@ function githubClient(overrides: Partial<GithubApiClient> = {}): GithubApiClient
     fetchRepositoryFile: vi.fn(() => {
       throw new Error('not used');
     }),
+    listRepositoryCommits: vi.fn(() => {
+      throw new Error('not used');
+    }),
     createInstallationAccessToken: vi.fn(() =>
       Promise.resolve({
         token: 'ghs_installationtoken',

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

@@ -57,6 +57,9 @@ function githubClient(overrides: Partial<GithubApiClient> = {}): GithubApiClient
         size: 58,
       }),
     ),
+    listRepositoryCommits: vi.fn(() =>
+      Promise.resolve([{sha: 'a'.repeat(40)}, {sha: 'b'.repeat(40)}]),
+    ),
     createInstallationAccessToken: vi.fn(() =>
       Promise.resolve({
         token: 'ghs_installationtoken',
@@ -259,6 +262,96 @@ describe('GithubSourceControlProvider', () => {
     });
   });
 
+  it('resolves a branch ref to the commit it points at', async () => {
+    await createInstallation();
+    const github = githubClient();
+    const provider = new GithubSourceControlProvider(github);
+
+    const result = await provider.resolveRef({
+      connection: connection(),
+      externalRepositoryId: 'github:42',
+      ref: 'refs/heads/main',
+    });
+
+    expect(result).toEqual({ref: 'refs/heads/main', commit: VALID_COMMIT});
+    expect(github.listRepositoryCommits).toHaveBeenCalledWith({
+      installationId,
+      repositoryId: 42,
+      ref: 'refs/heads/main',
+    });
+  });
+
+  it('resolves a tag ref to the commit it points at', async () => {
+    await createInstallation();
+    const github = githubClient({
+      listRepositoryCommits: vi.fn(() => Promise.resolve([{sha: 'c'.repeat(40)}])),
+    });
+    const provider = new GithubSourceControlProvider(github);
+
+    const result = await provider.resolveRef({
+      connection: connection(),
+      externalRepositoryId: 'github:42',
+      ref: 'refs/tags/v1.0.0',
+    });
+
+    expect(result).toEqual({ref: 'refs/tags/v1.0.0', commit: 'c'.repeat(40)});
+  });
+
+  it('maps a ref with no commits to ref-not-found', async () => {
+    await createInstallation();
+    const github = githubClient({
+      listRepositoryCommits: vi.fn(() => Promise.resolve([])),
+    });
+    const provider = new GithubSourceControlProvider(github);
+
+    const result = provider.resolveRef({
+      connection: connection(),
+      externalRepositoryId: 'github:42',
+      ref: 'refs/heads/missing',
+    });
+
+    await expect(result).rejects.toMatchObject({reason: 'ref-not-found'});
+  });
+
+  it('rejects a commit response with an invalid object id', async () => {
+    await createInstallation();
+    const github = githubClient({
+      listRepositoryCommits: vi.fn(() => Promise.resolve([{sha: 'not-a-commit'}])),
+    });
+    const provider = new GithubSourceControlProvider(github);
+
+    const result = provider.resolveRef({
+      connection: connection(),
+      externalRepositoryId: 'github:42',
+      ref: 'refs/heads/main',
+    });
+
+    await expect(result).rejects.toMatchObject({
+      reason: 'malformed-provider-response',
+      message: 'GitHub ref "refs/heads/main" resolved to an invalid commit',
+    });
+  });
+
+  it.each([
+    'a'.repeat(40),
+    'refs/pull/17/head',
+    'main',
+    '-evil',
+  ])('rejects ref %s as ref-invalid', async (ref) => {
+    await createInstallation();
+    const github = githubClient();
+    const provider = new GithubSourceControlProvider(github);
+
+    const result = provider.resolveRef({
+      connection: connection(),
+      externalRepositoryId: 'github:42',
+      ref,
+    });
+
+    await expect(result).rejects.toMatchObject({reason: 'ref-invalid'});
+    expect(github.listRepositoryCommits).not.toHaveBeenCalled();
+  });
+
   it('fetches repository file contents using the provider-owned repository id', async () => {
     await createInstallation();
     const github = githubClient();

package/src/core/source-control.ts

@@ -10,6 +10,7 @@ import {
   type IntegrationConnection,
   isRecord,
   isValidGitObjectId,
+  isValidResolvableRef,
   isValidTriggerRef,
   type ListFilesInput,
   type ListRepositoriesInput,
@@ -20,6 +21,8 @@ import {
   type RepositoryPage,
   type RepositorySnapshot,
   type RepositoryVisibility,
+  type ResolvedRef,
+  type ResolveRefInput,
   type ResolveRepositoryInput,
   type SourceControlProvider,
   type TriggerReference,
@@ -194,6 +197,37 @@ export class GithubSourceControlProvider
     };
   }
 
+  async resolveRef(input: ResolveRefInput<GithubIntegrationConnection>): Promise<ResolvedRef> {
+    if (!isValidResolvableRef(input.ref)) {
+      throw new GithubIntegrationProviderError(
+        'ref-invalid',
+        `GitHub ref ${formatRefForMessage(input.ref)} is not a resolvable branch or tag name`,
+      );
+    }
+    const installationId = await this.installationId(input.connection.id);
+    const {repositoryId} = parseGithubRepositoryLocator(input.externalRepositoryId);
+    const commits = await this.github.listRepositoryCommits({
+      installationId,
+      repositoryId,
+      ref: input.ref,
+    });
+    const commit = commits[0]?.sha;
+    if (!commit) {
+      throw new GithubIntegrationProviderError(
+        'ref-not-found',
+        `GitHub ref ${formatRefForMessage(input.ref)} does not resolve to a commit`,
+      );
+    }
+    if (!isValidGitObjectId(commit)) {
+      throw new GithubIntegrationProviderError(
+        'malformed-provider-response',
+        `GitHub ref ${formatRefForMessage(input.ref)} resolved to an invalid commit`,
+      );
+    }
+
+    return {ref: input.ref, commit};
+  }
+
   async createCheckoutSpec(
     input: CreateCheckoutSpecInput<GithubIntegrationConnection>,
   ): Promise<CheckoutSpec> {
@@ -256,6 +290,10 @@ function sameGithubRepository(
   return Boolean(firstName && secondName && firstName.toLowerCase() === secondName.toLowerCase());
 }
 
+function formatRefForMessage(ref: string): string {
+  return JSON.stringify(ref);
+}
+
 async function githubAppGitAuthor(
   github: GithubApiClient,
   installationAccessToken: string,

package/src/index.test.ts

@@ -1,3 +1,4 @@
+import {githubEventCatalog} from '@shipfox/api-integration-github-dto';
 import {githubInstallationTokenNamespace} from '#api/installation-token-envelope.js';
 import {createGithubIntegrationProvider} from '#index.js';
 
@@ -19,7 +20,7 @@ vi.mock('#core/webhook-processor.js', () => ({
 describe('createGithubIntegrationProvider', () => {
   it('shares installation-token cleanup with the direct and composed processors', async () => {
     const deleteSecrets = vi.fn(() => Promise.resolve(1));
-    createGithubIntegrationProvider({
+    const provider = createGithubIntegrationProvider({
       github: {} as never,
       getExistingGithubConnection: vi.fn(() => Promise.resolve(undefined)),
       connectGithubInstallation: vi.fn() as never,
@@ -31,6 +32,7 @@ describe('createGithubIntegrationProvider', () => {
       getIntegrationConnectionById: vi.fn(() => Promise.resolve(undefined)),
       deleteSecrets,
     });
+    expect(provider.eventCatalog).toBe(githubEventCatalog);
     const processorOptions = state.processorOptions as {
       deleteInstallationTokenSecret: (params: {
         workspaceId: string;

package/src/index.ts

@@ -1,3 +1,4 @@
+import {githubEventCatalog} from '@shipfox/api-integration-github-dto';
 import type {
   GetIntegrationConnectionByIdFn,
   PublishIntegrationEventReceivedFn,
@@ -102,6 +103,7 @@ export function createGithubIntegrationProvider(options: CreateGithubIntegration
   return {
     provider: 'github' as const,
     displayName: 'GitHub',
+    eventCatalog: githubEventCatalog,
     adapters: {
       source_control: new GithubSourceControlProvider(github),
       agent_tools: new GithubAgentToolsProvider({

package/src/presentation/routes/install.test.ts

@@ -61,6 +61,9 @@ function githubClient(overrides: Partial<GithubApiClient> = {}): GithubApiClient
     fetchRepositoryFile: vi.fn(() => {
       throw new Error('not used');
     }),
+    listRepositoryCommits: vi.fn(() => {
+      throw new Error('not used');
+    }),
     createInstallationAccessToken: vi.fn(() =>
       Promise.resolve({
         token: 'ghs_installationtoken',