Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
22.5 KB
Raw Blame
import { describe, expect, test } from 'bun:test';
import { mkdtempSync, mkdirSync, rmSync, writeFileSync, symlinkSync } from 'node:fs';
import { generateKeyPairSync } from 'node:crypto';
import { tmpdir } from 'node:os';
import { join } from 'node:path';

import {
  parseGitHubSourceConfig,
  isGitHubSourceConfig,
  extractLinkedNumbers,
  linkifyMentions,
  renderItemPage,
  renderListItemPage,
  renderRepoCard,
  itemPagePath,
  repoCardPath,
  isPageFresh,
  pageHasDetail,
  isValidRepoName,
  linkNextUrl,
  parseRetryAfterMs,
  mintAppInstallationToken,
  AppTokenProvider,
  type GitHubItemData,
} from '../src/core/github-source.ts';
import { extractGitHubItemRef } from '../src/commands/serve-http.ts';
import { GitHubClient } from '../src/core/github-source.ts';

function baseItemData(overrides: Partial<GitHubItemData> = {}): GitHubItemData {
  return {
    repo: 'acme/app',
    number: 42,
    kind: 'issue',
    detail: {
      number: 42,
      title: 'Fix the thing',
      state: 'open',
      state_reason: null,
      body: 'The thing is broken, see #7 and Closes #9.',
      created_at: '2026-08-01T00:00:00Z',
      updated_at: '2026-08-02T00:00:00Z',
      closed_at: null,
      labels: [{ name: 'bug' }, { name: 'p1' }],
      assignees: [{ login: 'alice' }],
      milestone: { title: 'v2', state: 'open' },
      html_url: 'https://github.com/acme/app/issues/42',
      user: { login: 'alice' },
    },
    comments: [
      { user: { login: 'bob' }, body: 'Can you also check #9?', created_at: '2026-08-01T01:00:00Z' },
    ],
    reviews: [],
    reviewComments: [],
    checks: null,
    linked: [9],
    ...overrides,
  };
}

describe('parseGitHubSourceConfig', () => {
  test('defaults for an empty config', () => {
    const cfg = parseGitHubSourceConfig({}, '/tmp/fallback');
    expect(cfg.tokenEnv).toBe('GH_TOKEN');
    expect(cfg.scope).toBe('auto');
    expect(cfg.repos).toEqual([]);
    expect(cfg.dir).toBe('/tmp/fallback');
  });

  test('reads explicit fields, lowercases repos, tolerates reserved keys', () => {
    const cfg = parseGitHubSourceConfig(
      {
        kind: 'github',
        gh_token_env: 'GH_MY_TOKEN',
        gh_handle: 'veltr', // reserved: tolerated, ignored
        gh_scope: 'repos',
        gh_repos: 'Acme/App, acme/tool',
        gh_dir: '/data/gh',
        gh_involvement: false, // reserved: tolerated, ignored
      },
      '/tmp/fallback',
    );
    expect(cfg.tokenEnv).toBe('GH_MY_TOKEN');
    expect(cfg.scope).toBe('repos');
    expect(cfg.repos).toEqual(['acme/app', 'acme/tool']);
    expect(cfg.dir).toBe('/data/gh');
  });

  test('drops malformed repo entries', () => {
    const cfg = parseGitHubSourceConfig(
      { kind: 'github', gh_scope: 'repos', gh_repos: 'acme/app,not-a-repo' },
      '/tmp/fallback',
    );
    expect(cfg.repos).toEqual(['acme/app']);
  });

  test('isGitHubSourceConfig detects the kind', () => {
    expect(isGitHubSourceConfig({ kind: 'github' })).toBe(true);
    expect(isGitHubSourceConfig({ kind: 'other' })).toBe(false);
    expect(isGitHubSourceConfig({})).toBe(false);
  });
});

describe('extractLinkedNumbers', () => {
  test('finds Closes/Fixes/Resolves references', () => {
    expect(extractLinkedNumbers('Closes #12 and fixes #34, resolves #56')).toEqual([12, 34, 56]);
  });
  test('case-insensitive and deduped', () => {
    expect(extractLinkedNumbers('FIXES #7\nfixes #7 again')).toEqual([7]);
  });
  test('ignores bare mentions', () => {
    expect(extractLinkedNumbers('see #99 for context')).toEqual([]);
  });
});

describe('linkifyMentions', () => {
  test('links #n mentions to the item page', () => {
    const out = linkifyMentions('see #7 and #12 here', 'acme/app');
    expect(out).toContain('[[gh/acme/app/7|#7]]');
    expect(out).toContain('[[gh/acme/app/12|#12]]');
  });
  test('does not link inside words or hashes', () => {
    expect(linkifyMentions('C# code and #x', 'acme/app')).toBe('C# code and #x');
  });
});

describe('renderItemPage', () => {
  test('issue page frontmatter and body', () => {
    const page = renderItemPage(baseItemData());
    expect(page).toContain('kind: issue');
    expect(page).toContain('repo: "acme/app"');
    expect(page).toContain('number: 42');
    expect(page).toContain('state: open');
    expect(page).toContain('status: "open"');
    expect(page).toContain('milestone: "v2"');
    expect(page).toContain('labels:');
    expect(page).toContain('  - "bug"');
    expect(page).toContain('  - "p1"');
    expect(page).toContain('  - "alice"');
    expect(page).toContain('## Description');
    expect(page).toContain('[[gh/acme/app/9|#9]]');
    expect(page).toContain('## Comments');
    expect(page).toContain('### bob · 2026-08-01T01:00:00Z');
    expect(page).toContain('## Linked');
    expect(page).toContain('[[gh/acme/app/9|#9]]');
  });

  test('pr page carries merge and review state', () => {
    const page = renderItemPage(
      baseItemData({
        kind: 'pr',
        detail: {
          ...baseItemData().detail,
          state: 'closed',
          closed_at: '2026-08-03T00:00:00Z',
          merged: true,
          mergeable_state: null,
          review_decision: 'APPROVED',
          head: { sha: 'abc123', ref: 'feat/thing' },
        } as GitHubItemData['detail'],
        reviews: [{ user: { login: 'carol' }, state: 'APPROVED', body: 'LGTM, see #88.', submitted_at: '2026-08-02T00:00:00Z' }],
      }),
    );
    expect(page).toContain('kind: pr');
    expect(page).toContain('status: "merged"');
    expect(page).toContain('merged: true');
    expect(page).toContain('head_ref: "feat/thing"');
    expect(page).toContain('## Reviews');
    expect(page).toContain('[[gh/acme/app/88|#88]]');
    expect(page).toContain('### carol · APPROVED · 2026-08-02T00:00:00Z');
  });

  test('open pr with checks emits check counts', () => {
    const page = renderItemPage(
      baseItemData({
        kind: 'pr',
        detail: {
          ...baseItemData().detail,
          state: 'open',
          merged: false,
          mergeable_state: 'clean',
          review_decision: 'CHANGES_REQUESTED',
          head: { sha: 'abc123', ref: 'feat/x' },
        } as GitHubItemData['detail'],
        checks: { pass: 3, fail: 1, pending: 2, failing: ['lint'] },
      }),
    );
    expect(page).toContain('checks_pass: 3');
    expect(page).toContain('checks_fail: 1');
    expect(page).toContain('checks_pending: 2');
    expect(page).toContain('**Checks:** 3 passing, 1 failing, 2 pending');
    expect(page).toContain('Failing: lint');
  });

  test('review comments carry file and line', () => {
    const page = renderItemPage(
      baseItemData({
        reviewComments: [
          {
            user: { login: 'dave' },
            body: 'off by one here; see #89',
            created_at: '2026-08-02T02:00:00Z',
            path: 'src/app.ts',
            line: 41,
            original_line: null,
          },
        ],
      }),
    );
    expect(page).toContain('## Review comments');
    expect(page).toContain('[[gh/acme/app/89|#89]]');
    expect(page).toContain('### dave · src/app.ts:41 · 2026-08-02T02:00:00Z');
  });
});

describe('renderRepoCard', () => {
  test('emits repo metadata', () => {
    const page = renderRepoCard('acme/app', {
      full_name: 'acme/app',
      private: true,
      archived: false,
      default_branch: 'main',
      description: 'The app',
    });
    expect(page).toContain('kind: repo');
    expect(page).toContain('repo: "acme/app"');
    expect(page).toContain('description: "The app"');
    expect(page).toContain('archived: false');
    expect(page).toContain('Default branch: main');
  });
});

describe('isValidRepoName', () => {
  test('accepts normal owner/name', () => {
    expect(isValidRepoName('acme/app')).toBe(true);
    expect(isValidRepoName('a.b-c_d/app')).toBe(true);
  });
  test('rejects dot segments and malformed shapes', () => {
    expect(isValidRepoName('../..')).toBe(false);
    expect(isValidRepoName('..')).toBe(false);
    expect(isValidRepoName('.')).toBe(false);
    expect(isValidRepoName('acme/..')).toBe(false);
    expect(isValidRepoName('/acme/app')).toBe(false);
    expect(isValidRepoName('acme/app/')).toBe(false);
    expect(isValidRepoName('acme')).toBe(false);
    expect(isValidRepoName('a/b/c')).toBe(false);
    expect(isValidRepoName('')).toBe(false);
  });
});

describe('linkNextUrl', () => {
  test('extracts rel=next from a Link header', () => {
    const header =
      '<https://api.github.com/repos/a/b/issues?page=2&per_page=100>; rel="next", ' +
      '<https://api.github.com/repos/a/b/issues?page=4&per_page=100>; rel="last"';
    expect(linkNextUrl(header)).toBe('https://api.github.com/repos/a/b/issues?page=2&per_page=100');
  });
  test('returns null when no next link exists', () => {
    expect(linkNextUrl('<https://x>; rel="last"')).toBeNull();
    expect(linkNextUrl('')).toBeNull();
  });
});

describe('fetchAllPages', () => {
  test('follows absolute Link URLs without double-prefixing the host', async () => {
    const calls: string[] = [];
    const client = new GitHubClient('tok', (async (u: string): Promise<Response> => {
      calls.push(u);
      const h = new Headers();
      if (calls.length === 1) {
        h.set('link', '<https://api.github.com/repos/a/b/issues?page=2&per_page=100>; rel="next"');
      }
      return new Response(JSON.stringify([{ n: calls.length }]), { status: 200, headers: h });
    }) as never);
    const out = await client.fetchAllPages<{ n: number }>('/repos/a/b/issues');
    expect(calls).toEqual([
      'https://api.github.com/repos/a/b/issues?per_page=100&page=1',
      'https://api.github.com/repos/a/b/issues?page=2&per_page=100',
    ]);
    expect(out).toEqual([{ n: 1 }, { n: 2 }]);
  });

  test('non-array field payload throws naming the endpoint and field', async () => {
    const client = new GitHubClient('tok', (async () =>
      new Response(JSON.stringify({ check_runs: 'nope' }), { status: 200 })) as never);
    await expect(
      client.fetchAllPages('/repos/a/b/commits/abc/check-runs', { field: 'check_runs' }),
    ).rejects.toThrow('non-array payload on /repos/a/b/commits/abc/check-runs (field "check_runs")');
  });

  test('non-array payload without a field throws naming the endpoint', async () => {
    const client = new GitHubClient('tok', (async () =>
      new Response(JSON.stringify({ message: 'moved' }), { status: 200 })) as never);
    await expect(client.fetchAllPages('/repos/a/b/issues')).rejects.toThrow(
      'non-array payload on /repos/a/b/issues',
    );
  });
});

describe('parseRetryAfterMs', () => {
  test('delta-seconds form', () => {
    expect(parseRetryAfterMs('120')).toBe(120_000);
    expect(parseRetryAfterMs('0')).toBe(0);
  });

  test('HTTP-date form (future waits, past is 0)', () => {
    const now = Math.floor(Date.now() / 1000) * 1000; // HTTP-dates drop ms
    expect(parseRetryAfterMs(new Date(now + 120_000).toUTCString(), now)).toBe(120_000);
    expect(parseRetryAfterMs(new Date(now - 60_000).toUTCString(), now)).toBe(0);
  });

  test('absent or garbage is null, never NaN', () => {
    expect(parseRetryAfterMs(null)).toBeNull();
    expect(parseRetryAfterMs('')).toBeNull();
    expect(parseRetryAfterMs('soon')).toBeNull();
  });
});

describe('GitHubClient 403/429 handling', () => {
  const jsonRes = (body: unknown, status: number, headers: Record<string, string> = {}): Response =>
    new Response(JSON.stringify(body), { status, headers });

  test('403 with rate budget left and no Retry-After fails fast', async () => {
    let calls = 0;
    const client = new GitHubClient('tok', (async () => {
      calls++;
      return jsonRes({ message: 'Resource not accessible' }, 403, {
        'x-ratelimit-remaining': '4000',
        'x-ratelimit-reset': String(Math.floor(Date.now() / 1000) + 3600),
      });
    }) as never);
    await expect(client.fetchJSON('/repos/a/b/issues')).rejects.toThrow('check token permissions');
    expect(calls).toBe(1); // no useless retry against a permission error
  });

  test('403 with an exhausted bucket retries after the reset', async () => {
    let calls = 0;
    const resetSec = Math.floor(Date.now() / 1000) - 2; // already elapsed
    const client = new GitHubClient('tok', (async () => {
      calls++;
      if (calls === 1) {
        return jsonRes({ message: 'rate limited' }, 403, {
          'x-ratelimit-remaining': '0',
          'x-ratelimit-reset': String(resetSec),
        });
      }
      return jsonRes([{ ok: true }], 200, {
        'x-ratelimit-remaining': '5000',
        'x-ratelimit-reset': String(resetSec + 3600),
      });
    }) as never);
    const out = await client.fetchJSON<Array<{ ok: boolean }>>('/repos/a/b/issues');
    expect(calls).toBe(2);
    expect(out).toEqual([{ ok: true }]);
  }, 10_000);

  test('429 with an HTTP-date Retry-After in the past retries without a NaN sleep', async () => {
    let calls = 0;
    const client = new GitHubClient('tok', (async () => {
      calls++;
      if (calls === 1) {
        return jsonRes({}, 429, { 'retry-after': new Date(Date.now() - 5000).toUTCString() });
      }
      return jsonRes([1], 200);
    }) as never);
    const started = Date.now();
    const out = await client.fetchJSON<number[]>('/x');
    expect(calls).toBe(2);
    expect(out).toEqual([1]);
    expect(Date.now() - started).toBeLessThan(5000);
  });
});

describe('symlink containment', () => {
  test('itemPagePath refuses a gh/ symlink escaping the managed dir', () => {
    const outside = mkdtempSync(join(tmpdir(), 'ghsrc-outside-'));
    const dir = mkdtempSync(join(tmpdir(), 'ghsrc-managed-'));
    try {
      // A lexical prefix check passes here — only realpath containment
      // catches the planted symlinked intermediate directory.
      symlinkSync(outside, join(dir, 'gh'));
      expect(() => itemPagePath(dir, 'acme/app', 7)).toThrow('Path escapes managed dir');
      expect(() => repoCardPath(dir, 'acme/app')).toThrow('Path escapes managed dir');
    } finally {
      rmSync(dir, { recursive: true, force: true });
      rmSync(outside, { recursive: true, force: true });
    }
  });
});

describe('extractGitHubItemRef (webhook payload shapes)', () => {
  const repo = { full_name: 'acme/app' };
  test('issue event', () => {
    expect(extractGitHubItemRef({ repository: repo, issue: { number: 7 } })).toEqual({ repo: 'acme/app', number: 7, kind: 'issue' });
  });
  test('PR issue_comment event carries the PR inside issue.pull_request', () => {
    expect(
      extractGitHubItemRef({ repository: repo, issue: { number: 9, pull_request: {} } }),
    ).toEqual({ repo: 'acme/app', number: 9, kind: 'pr' });
  });
  test('pull_request review event', () => {
    expect(
      extractGitHubItemRef({ repository: repo, pull_request: { number: 12 } }),
    ).toEqual({ repo: 'acme/app', number: 12, kind: 'pr' });
  });
  test('check_run event nests linked PRs', () => {
    expect(
      extractGitHubItemRef({ repository: repo, check_run: { pull_requests: [{ number: 15 }] } }),
    ).toEqual({ repo: 'acme/app', number: 15, kind: 'pr' });
  });
  test('check_suite and workflow_run also nest linked PRs', () => {
    expect(
      extractGitHubItemRef({ repository: repo, check_suite: { pull_requests: [{ number: 16 }] } }),
    ).toEqual({ repo: 'acme/app', number: 16, kind: 'pr' });
    expect(
      extractGitHubItemRef({ repository: repo, workflow_run: { pull_requests: [{ number: 17 }] } }),
    ).toEqual({ repo: 'acme/app', number: 17, kind: 'pr' });
  });
  test('payload without an item reference resolves to null', () => {
    expect(extractGitHubItemRef({ repository: repo, check_run: { pull_requests: [] } })).toBeNull();
    expect(extractGitHubItemRef({ repository: repo, zen: 'hi' })).toBeNull();
    expect(extractGitHubItemRef({})).toBeNull();
  });
});

describe('paths and freshness', () => {
  test('item and card paths', () => {
    expect(itemPagePath('/base', 'acme/app', 7)).toBe(join('/base', 'gh', 'acme/app', '7.md'));
    expect(repoCardPath('/base', 'acme/app')).toBe(join('/base', 'gh', 'acme/app', 'index.md'));
  });

  test('isPageFresh compares stored vs API updated_at', () => {
    const dir = mkdtempSync(join(tmpdir(), 'ghsrc-page-'));
    try {
      const p = join(dir, 'x.md');
      mkdirSync(dir, { recursive: true });
      writeFileSync(p, '---\nupdated_at: "2026-08-02T00:00:00Z"\n---\nbody', 'utf-8');
      expect(isPageFresh(p, '2026-08-01T00:00:00Z')).toBe(true);
      expect(isPageFresh(p, '2026-08-02T00:00:00Z')).toBe(true);
      expect(isPageFresh(p, '2026-08-03T00:00:00Z')).toBe(false);
      expect(isPageFresh(join(dir, 'missing.md'), '2026-08-01T00:00:00Z')).toBe(false);
      expect(isPageFresh(join(dir, 'no-fm.md'), '2026-08-01T00:00:00Z')).toBe(false);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });
});

describe('fast path (two-pass)', () => {
  test('renderListItemPage emits a list-only page marked detail_fetched: false', () => {
    const page = renderListItemPage('acme/app', 'issue', {
      number: 7,
      title: 'List title',
      state: 'open',
      updated_at: '2026-08-04T00:00:00Z',
      body: 'Closes #9 body text',
      html_url: 'https://github.com/acme/app/issues/7',
      created_at: '2026-08-01T00:00:00Z',
      labels: [{ name: 'bug' }],
      assignees: [{ login: 'alice' }],
      user: { login: 'bob' },
    });
    expect(page).toContain('detail_fetched: false');
    expect(page).toContain('title: "List title"');
    expect(page).toContain('## Description');
    expect(page).toContain('[[gh/acme/app/9|#9]]');
    // No detail sections until pass 2.
    expect(page).not.toContain('## Comments');
    expect(page).not.toContain('## Reviews');
  });

  test('pageHasDetail: missing marker means complete (pre-change pages), false means pending', () => {
    const dir = mkdtempSync(join(tmpdir(), 'ghsrc-detail-'));
    try {
      const old = join(dir, 'old.md');
      writeFileSync(old, '---\nupdated_at: "2026-08-01T00:00:00Z"\n---\nbody', 'utf-8');
      expect(pageHasDetail(old)).toBe(true);
      const pending = join(dir, 'pending.md');
      writeFileSync(pending, '---\ndetail_fetched: false\n---\nbody', 'utf-8');
      expect(pageHasDetail(pending)).toBe(false);
      const done = join(dir, 'done.md');
      writeFileSync(done, '---\ndetail_fetched: true\n---\nbody', 'utf-8');
      expect(pageHasDetail(done)).toBe(true);
      // A missing file has no detail yet: pass 1 materializes it first.
      expect(pageHasDetail(join(dir, 'missing.md'))).toBe(false);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });
});

describe('GitHub App tokens', () => {
  function tempKey(): { dir: string; pemPath: string } {
    const dir = mkdtempSync(join(tmpdir(), 'ghsrc-app-'));
    const { privateKey } = generateKeyPairSync('rsa', { modulusLength: 2048 });
    const pemPath = join(dir, 'key.pem');
    writeFileSync(pemPath, privateKey.export({ type: 'pkcs8', format: 'pem' }), 'utf-8');
    return { dir, pemPath };
  }

  test('mintAppInstallationToken signs a JWT, discovers the install and mints', async () => {
    const { dir, pemPath } = tempKey();
    try {
      const calls: Array<{ url: string; auth: string }> = [];
      const fakeFetch = async (url: string, init: RequestInit): Promise<Response> => {
        const auth = String((init.headers as Record<string, string>).authorization);
        calls.push({ url, auth });
        if (url.endsWith('/app/installations')) {
          return new Response(JSON.stringify([{ id: 153578804 }]), { status: 200 });
        }
        if (url.includes('/access_tokens')) {
          return new Response(
            JSON.stringify({ token: 'ghs_install-token', expires_at: '2026-08-14T02:00:00Z' }),
            { status: 200 },
          );
        }
        return new Response('{}', { status: 404 });
      };
      const out = await mintAppInstallationToken({ appId: 4588667, pemPath }, fakeFetch);
      expect(out.token).toBe('ghs_install-token');
      expect(out.expiresAt).toBe(Date.parse('2026-08-14T02:00:00Z'));
      expect(calls.length).toBe(2);
      expect(calls[0].url).toContain('/app/installations');
      // Bearer is an RS256 JWT: decode the payload, check iss/exp window.
      const jwt = calls[0].auth.replace('Bearer ', '');
      const payload = JSON.parse(Buffer.from(jwt.split('.')[1], 'base64url').toString('utf-8'));
      expect(payload.iss).toBe(4588667);
      expect(payload.exp - payload.iat).toBe(540);
      expect(calls[1].url).toContain('/app/installations/153578804/access_tokens');
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  test('explicit install id skips discovery', async () => {
    const { dir, pemPath } = tempKey();
    try {
      const urls: string[] = [];
      const fakeFetch = async (url: string, init: RequestInit): Promise<Response> => {
        urls.push(url);
        return new Response(
          JSON.stringify({ token: 'ghs_x', expires_at: '2026-08-14T02:00:00Z' }),
          { status: 200 },
        );
      };
      await mintAppInstallationToken({ appId: 1, pemPath, installId: 99 }, fakeFetch);
      expect(urls).toEqual(['https://api.github.com/app/installations/99/access_tokens']);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  test('AppTokenProvider caches within the window and refreshes after expiry', async () => {
    const { dir, pemPath } = tempKey();
    try {
      let mints = 0;
      const fakeFetch = async (url: string, _init: RequestInit): Promise<Response> => {
        if (url.includes('/access_tokens')) {
          mints++;
          return new Response(
            JSON.stringify({
              token: `ghs_${mints}`,
              expires_at: new Date(Date.now() + 60 * 60_000).toISOString(),
            }),
            { status: 200 },
          );
        }
        return new Response(JSON.stringify([{ id: 1 }]), { status: 200 });
      };
      const provider = new AppTokenProvider({ appId: 1, pemPath }, fakeFetch);
      expect(await provider.getToken()).toBe('ghs_1');
      expect(await provider.getToken()).toBe('ghs_1'); // cached
      expect(mints).toBe(1);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });
});

describe('parseGitHubSourceConfig app fields', () => {
  test('parses app credentials when present', () => {
    const cfg = parseGitHubSourceConfig(
      {
        kind: 'github',
        gh_app_id: 4588667,
        gh_app_pem_path: '/keys/app.pem',
        gh_app_install_id: 153578804,
      },
      '/tmp/fallback',
    );
    expect(cfg.app).toEqual({ appId: 4588667, pemPath: '/keys/app.pem', installId: 153578804 });
  });

  test('partial app config yields null (PAT path unchanged)', () => {
    const cfg = parseGitHubSourceConfig(
      { kind: 'github', gh_app_id: 4588667 },
      '/tmp/fallback',
    );
    expect(cfg.app).toBeNull();
    expect(cfg.tokenEnv).toBe('GH_TOKEN');
  });
});