@shipfox/api-integration-github 2.0.0

package/src/connection-external-url.test.ts

@@ -0,0 +1,78 @@
+import type {GithubApiClient} from '#api/client.js';
+import type {GithubInstallation} from '#db/installations.js';
+import {createGithubIntegrationProvider} from '#index.js';
+
+function githubClient(): GithubApiClient {
+  return {
+    exchangeOAuthCode: vi.fn(() => Promise.resolve('user-token')),
+    listUserInstallations: vi.fn(() => Promise.resolve({installationIds: [], nextCursor: null})),
+    getInstallation: vi.fn(() => Promise.reject(new Error('not used'))),
+    listInstallationRepositories: vi.fn(() => Promise.reject(new Error('not used'))),
+    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'))),
+    createInstallationToken: vi.fn(() => Promise.reject(new Error('not used'))),
+  } as unknown as GithubApiClient;
+}
+
+function installation(overrides: Partial<GithubInstallation> = {}): GithubInstallation {
+  return {
+    id: crypto.randomUUID(),
+    connectionId: crypto.randomUUID(),
+    installationId: '123',
+    accountLogin: 'shipfox',
+    accountType: 'Organization',
+    repositorySelection: 'all',
+    suspendedAt: null,
+    deletedAt: null,
+    latestEvent: {},
+    installerUserId: null,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    ...overrides,
+  };
+}
+
+function createProvider(lookup: (connectionId: string) => Promise<GithubInstallation | undefined>) {
+  return createGithubIntegrationProvider({
+    github: githubClient(),
+    getExistingGithubConnection: vi.fn(() => Promise.resolve(undefined)),
+    connectGithubInstallation: vi.fn() as never,
+    coreDb: vi.fn() as never,
+    publishIntegrationEventReceived: vi.fn(() => Promise.resolve({published: false})),
+    publishSourcePush: vi.fn(() => Promise.resolve({published: false})),
+    recordDeliveryOnly: vi.fn(() => Promise.resolve()),
+    getIntegrationConnectionById: vi.fn(() => Promise.resolve(undefined)),
+    getGithubInstallationByConnectionId: lookup,
+  });
+}
+
+describe('github connectionExternalUrl', () => {
+  it('resolves the organization installation settings URL for org accounts', async () => {
+    const provider = createProvider(() =>
+      Promise.resolve(installation({accountType: 'Organization', accountLogin: 'acme'})),
+    );
+
+    const url = await provider.connectionExternalUrl({id: crypto.randomUUID()});
+
+    expect(url).toBe('https://github.com/organizations/acme/settings/installations/123');
+  });
+
+  it('resolves the user installation settings URL for user accounts', async () => {
+    const provider = createProvider(() =>
+      Promise.resolve(installation({accountType: 'User', accountLogin: 'octocat'})),
+    );
+
+    const url = await provider.connectionExternalUrl({id: crypto.randomUUID()});
+
+    expect(url).toBe('https://github.com/settings/installations/123');
+  });
+
+  it('returns undefined when the installation row is missing', async () => {
+    const provider = createProvider(() => Promise.resolve(undefined));
+
+    const url = await provider.connectionExternalUrl({id: crypto.randomUUID()});
+
+    expect(url).toBeUndefined();
+  });
+});

package/src/core/actions-logs.test.ts

@@ -0,0 +1,156 @@
+import {
+  buildGithubFailedJobLogsResult,
+  buildGithubSingleJobLogResult,
+  DEFAULT_JOB_LOG_TAIL_LINES,
+  MAX_JOB_LOG_LINE_BYTES,
+  MAX_TRUNCATED_JOB_LOG_LINE_CHARS,
+  processGithubJobLogContent,
+} from './actions-logs.js';
+
+describe('buildGithubSingleJobLogResult', () => {
+  it('returns a logs URL without fetching content by default', async () => {
+    const fetchContent = vi.fn(() => Promise.resolve('full log'));
+
+    const result = await buildGithubSingleJobLogResult({
+      job: job({fetchContent}),
+    });
+
+    expect(fetchContent).not.toHaveBeenCalled();
+    expect(result).toEqual({
+      job_id: 1,
+      job_name: 'Unit tests',
+      logs_url: 'https://github.example/logs/1',
+      message: 'Job logs are available for download',
+      note: 'The logs_url provides a download link for the individual job logs in plain text format.\nUse return_content=true to get the actual log content.',
+    });
+  });
+
+  it('returns default tail content when content is requested', async () => {
+    const lines = Array.from(
+      {length: DEFAULT_JOB_LOG_TAIL_LINES + 50},
+      (_value, index) => `line ${index + 1}`,
+    );
+
+    const result = await buildGithubSingleJobLogResult({
+      job: job({fetchContent: async () => lines.join('\n')}),
+      returnContent: true,
+    });
+
+    expect(result).toEqual({
+      job_id: 1,
+      job_name: 'Unit tests',
+      logs_content: lines.slice(-DEFAULT_JOB_LOG_TAIL_LINES).join('\n'),
+      message: 'Job logs content retrieved successfully',
+      original_length: DEFAULT_JOB_LOG_TAIL_LINES + 50,
+    });
+  });
+});
+
+describe('buildGithubFailedJobLogsResult', () => {
+  it('reports when a workflow run has no failed jobs', async () => {
+    const result = await buildGithubFailedJobLogsResult({
+      runId: 123,
+      jobs: [job({conclusion: 'success'})],
+    });
+
+    expect(result).toEqual({
+      message: 'No failed jobs found in this workflow run',
+      run_id: 123,
+      total_jobs: 1,
+      failed_jobs: 0,
+    });
+  });
+
+  it('returns logs for every failed job without a failed-job cap', async () => {
+    const jobs = Array.from({length: 25}, (_value, index) =>
+      job({jobId: index + 1, conclusion: index % 2 === 0 ? 'failure' : 'success'}),
+    );
+
+    const result = await buildGithubFailedJobLogsResult({runId: 123, jobs});
+
+    expect(result).toMatchObject({
+      message: 'Retrieved logs for 13 failed jobs',
+      run_id: 123,
+      total_jobs: 25,
+      failed_jobs: 13,
+      return_format: {content: false, urls: true},
+    });
+    expect(result.logs).toHaveLength(13);
+    expect(result.logs?.[0]).toMatchObject({
+      job_id: 1,
+      job_name: 'Unit tests',
+      logs_url: 'https://github.example/logs/1',
+    });
+  });
+
+  it('keeps failed-job fetch errors local to the affected job', async () => {
+    const result = await buildGithubFailedJobLogsResult({
+      runId: 123,
+      returnContent: true,
+      jobs: [
+        job({
+          conclusion: 'failure',
+          fetchContent: () => Promise.reject(new Error('download failed')),
+        }),
+      ],
+    });
+
+    expect(result.logs).toEqual([
+      {
+        job_id: 1,
+        job_name: 'Unit tests',
+        error: 'download failed',
+      },
+    ]);
+  });
+});
+
+describe('processGithubJobLogContent', () => {
+  it('uses the smaller of tail_lines and content window size', () => {
+    const lines = Array.from({length: 10}, (_value, index) => `line ${index + 1}`);
+
+    const result = processGithubJobLogContent(lines.join('\n'), {
+      tailLines: 8,
+      contentWindowSize: 3,
+    });
+
+    expect(result).toEqual({
+      content: ['line 8', 'line 9', 'line 10'].join('\n'),
+      totalLines: 10,
+    });
+  });
+
+  it('defaults invalid tail_lines to 500', () => {
+    const lines = Array.from(
+      {length: DEFAULT_JOB_LOG_TAIL_LINES + 1},
+      (_value, index) => `line ${index + 1}`,
+    );
+
+    const result = processGithubJobLogContent(lines.join('\n'), {tailLines: 0});
+
+    expect(result.content).toBe(lines.slice(-DEFAULT_JOB_LOG_TAIL_LINES).join('\n'));
+    expect(result.totalLines).toBe(DEFAULT_JOB_LOG_TAIL_LINES + 1);
+  });
+
+  it('truncates extremely long single lines', () => {
+    const line = 'a'.repeat(MAX_JOB_LOG_LINE_BYTES + 1);
+
+    const result = processGithubJobLogContent(line);
+
+    expect(result.content).toBe(`${'a'.repeat(MAX_TRUNCATED_JOB_LOG_LINE_CHARS)}...\n[TRUNCATED]`);
+    expect(result.totalLines).toBe(1);
+  });
+});
+
+function job(
+  overrides: Partial<Parameters<typeof buildGithubSingleJobLogResult>[0]['job']> = {},
+): Parameters<typeof buildGithubSingleJobLogResult>[0]['job'] {
+  const jobId = overrides.jobId ?? 1;
+  return {
+    jobId,
+    name: 'Unit tests',
+    conclusion: 'failure',
+    logsUrl: `https://github.example/logs/${jobId}`,
+    ...overrides,
+  };
+}

package/src/core/actions-logs.ts

@@ -0,0 +1,186 @@
+import {Buffer} from 'node:buffer';
+
+export const DEFAULT_JOB_LOG_TAIL_LINES = 500;
+export const DEFAULT_JOB_LOG_CONTENT_WINDOW_LINES = 5000;
+export const MAX_JOB_LOG_RING_BUFFER_LINES = 100000;
+export const MAX_JOB_LOG_LINE_BYTES = 10 * 1024 * 1024;
+export const MAX_TRUNCATED_JOB_LOG_LINE_CHARS = 1000;
+
+export interface GithubJobLogSource {
+  jobId: number;
+  name?: string | undefined;
+  conclusion?: string | undefined;
+  logsUrl: string;
+  fetchContent?: (() => Promise<string>) | undefined;
+}
+
+export interface BuildGithubSingleJobLogResultInput {
+  job: GithubJobLogSource;
+  returnContent?: boolean | undefined;
+  tailLines?: number | undefined;
+  contentWindowSize?: number | undefined;
+}
+
+export interface BuildGithubFailedJobLogsResultInput {
+  jobs: readonly GithubJobLogSource[];
+  runId: number;
+  returnContent?: boolean | undefined;
+  tailLines?: number | undefined;
+  contentWindowSize?: number | undefined;
+}
+
+export type GithubJobLogResult = Record<string, unknown>;
+
+export interface GithubFailedJobLogsResult {
+  message: string;
+  run_id: number;
+  total_jobs: number;
+  failed_jobs: number;
+  logs?: GithubJobLogResult[] | undefined;
+  return_format?: {content: boolean; urls: boolean} | undefined;
+}
+
+export function buildGithubSingleJobLogResult(
+  input: BuildGithubSingleJobLogResultInput,
+): Promise<GithubJobLogResult> {
+  return buildGithubJobLogData(input);
+}
+
+export async function buildGithubFailedJobLogsResult(
+  input: BuildGithubFailedJobLogsResultInput,
+): Promise<GithubFailedJobLogsResult> {
+  const failedJobs = input.jobs.filter((job) => job.conclusion === 'failure');
+
+  if (failedJobs.length === 0) {
+    return {
+      message: 'No failed jobs found in this workflow run',
+      run_id: input.runId,
+      total_jobs: input.jobs.length,
+      failed_jobs: 0,
+    };
+  }
+
+  const logs: GithubJobLogResult[] = [];
+  for (const job of failedJobs) {
+    try {
+      logs.push(await buildGithubJobLogData({job, ...input}));
+    } catch (error) {
+      logs.push({
+        job_id: job.jobId,
+        ...(job.name ? {job_name: job.name} : {}),
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  return {
+    message: `Retrieved logs for ${failedJobs.length} failed jobs`,
+    run_id: input.runId,
+    total_jobs: input.jobs.length,
+    failed_jobs: failedJobs.length,
+    logs,
+    return_format: {content: input.returnContent === true, urls: input.returnContent !== true},
+  };
+}
+
+function buildGithubJobLogData(
+  input: BuildGithubSingleJobLogResultInput,
+): Promise<GithubJobLogResult> {
+  const result: GithubJobLogResult = {
+    job_id: input.job.jobId,
+    ...(input.job.name ? {job_name: input.job.name} : {}),
+  };
+
+  if (input.returnContent === true) {
+    const content = input.job.fetchContent ? input.job.fetchContent() : Promise.resolve('');
+    return content.then((logsContent) => {
+      const processed = processGithubJobLogContent(logsContent, {
+        tailLines: input.tailLines,
+        contentWindowSize: input.contentWindowSize,
+      });
+      return {
+        ...result,
+        logs_content: processed.content,
+        message: 'Job logs content retrieved successfully',
+        original_length: processed.totalLines,
+      };
+    });
+  }
+
+  return Promise.resolve({
+    ...result,
+    logs_url: input.job.logsUrl,
+    message: 'Job logs are available for download',
+    note: 'The logs_url provides a download link for the individual job logs in plain text format.\nUse return_content=true to get the actual log content.',
+  });
+}
+
+export function processGithubJobLogContent(
+  content: string,
+  options: {tailLines?: number | undefined; contentWindowSize?: number | undefined} = {},
+): {content: string; totalLines: number} {
+  const tailLines = normalizeTailLines(options.tailLines);
+  const maxLines = Math.min(
+    tailLines,
+    options.contentWindowSize ?? DEFAULT_JOB_LOG_CONTENT_WINDOW_LINES,
+  );
+  const processed = processResponseAsRingBufferToEnd(content, maxLines);
+  const lines = processed.content.split('\n');
+  const finalLines = lines.length > tailLines ? lines.slice(-tailLines) : lines;
+
+  return {content: finalLines.join('\n'), totalLines: processed.totalLines};
+}
+
+function normalizeTailLines(tailLines: number | undefined): number {
+  if (tailLines === undefined) return DEFAULT_JOB_LOG_TAIL_LINES;
+  if (!Number.isFinite(tailLines) || tailLines <= 0) return DEFAULT_JOB_LOG_TAIL_LINES;
+  return Math.trunc(tailLines);
+}
+
+function processResponseAsRingBufferToEnd(
+  content: string,
+  maxJobLogLines: number,
+): {content: string; totalLines: number} {
+  let maxLines = Math.trunc(maxJobLogLines);
+  if (maxLines <= 0) maxLines = DEFAULT_JOB_LOG_TAIL_LINES;
+  if (maxLines > MAX_JOB_LOG_RING_BUFFER_LINES) maxLines = MAX_JOB_LOG_RING_BUFFER_LINES;
+
+  const lines = new Array<string>(maxLines);
+  const validLines = new Array<boolean>(maxLines).fill(false);
+  let totalLines = 0;
+  let writeIndex = 0;
+
+  const storeLine = (line: string) => {
+    lines[writeIndex] = truncateLongLine(line);
+    validLines[writeIndex] = true;
+    totalLines += 1;
+    writeIndex = (writeIndex + 1) % maxLines;
+  };
+
+  for (const line of splitLogLines(content)) {
+    storeLine(line);
+  }
+
+  const result: string[] = [];
+  const linesInBuffer = Math.min(totalLines, maxLines);
+  const startIndex = totalLines > maxLines ? writeIndex : 0;
+
+  for (let offset = 0; offset < linesInBuffer; offset += 1) {
+    const index = (startIndex + offset) % maxLines;
+    if (validLines[index]) result.push(lines[index] ?? '');
+  }
+
+  return {content: result.join('\n'), totalLines};
+}
+
+function splitLogLines(content: string): string[] {
+  if (content.length === 0) return [];
+  const lines = content.split('\n');
+  if (content.endsWith('\n')) lines.pop();
+  return lines;
+}
+
+function truncateLongLine(line: string): string {
+  if (Buffer.byteLength(line, 'utf8') < MAX_JOB_LOG_LINE_BYTES) return line;
+  return `${Array.from(line).slice(0, MAX_TRUNCATED_JOB_LOG_LINE_CHARS).join('')}...\n[TRUNCATED]`;
+}

package/src/core/agent-tool-selection.test.ts

@@ -0,0 +1,41 @@
+import {githubAgentToolSelectionCatalog} from './agent-tools.js';
+
+describe('githubAgentToolSelectionCatalog', () => {
+  const selectors = new Map(
+    githubAgentToolSelectionCatalog.selectors.map((selector) => [selector.token, selector]),
+  );
+
+  it('expands family tools into bare, wildcard, and method selectors', () => {
+    expect(selectors.get('issue_read')).toMatchObject({
+      kind: 'family',
+      sensitivity: 'read',
+      sensitive: false,
+    });
+    expect(selectors.get('issue_read.*')).toMatchObject({
+      kind: 'family_wildcard',
+      sensitivity: 'read',
+      sensitive: false,
+    });
+    expect(selectors.get('issue_read.get')).toMatchObject({
+      kind: 'method',
+      sensitivity: 'read',
+      sensitive: false,
+    });
+  });
+
+  it('uses method sensitivity for method selectors', () => {
+    expect(selectors.get('actions_run_trigger.run_workflow')).toMatchObject({
+      kind: 'method',
+      sensitivity: 'write',
+      sensitive: true,
+    });
+  });
+
+  it('keeps standalone tools as standalone selectors', () => {
+    expect(selectors.get('merge_pull_request')).toMatchObject({
+      kind: 'standalone',
+      sensitivity: 'write',
+      sensitive: true,
+    });
+  });
+});

package/src/core/agent-tool-selection.ts

@@ -0,0 +1,42 @@
+import type {AgentToolSelectionCatalog, AgentToolSelector} from '@shipfox/api-integration-core-dto';
+import type {GithubAgentToolCatalogEntry} from './agent-tools.js';
+
+export function buildGithubAgentToolSelectionCatalog(
+  catalog: readonly GithubAgentToolCatalogEntry[],
+): AgentToolSelectionCatalog {
+  return {
+    selectors: catalog.flatMap((entry): AgentToolSelector[] => {
+      if (!entry.methods) {
+        return [
+          {
+            token: entry.id,
+            kind: 'standalone',
+            sensitivity: entry.sensitivity,
+            sensitive: entry.sensitive,
+          },
+        ];
+      }
+
+      return [
+        {
+          token: entry.id,
+          kind: 'family',
+          sensitivity: entry.sensitivity,
+          sensitive: entry.sensitive,
+        },
+        {
+          token: `${entry.id}.*`,
+          kind: 'family_wildcard',
+          sensitivity: entry.sensitivity,
+          sensitive: entry.sensitive,
+        },
+        ...entry.methods.map((method) => ({
+          token: `${entry.id}.${method.id}`,
+          kind: 'method' as const,
+          sensitivity: method.sensitivity,
+          sensitive: method.sensitive,
+        })),
+      ];
+    }),
+  };
+}