Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* .github/workflows/fix-wave-gate.yml + scripts/fix-wave-gate.ts — the contributor gate.
*
* Protects: contributor PRs into master fail unless the head repository is
* garrytan/gbrain or a human maintainer applied `maintainer-override`; GBRA
* thread PRs (same-repo heads) always pass; a PR cannot change its own result
* by editing the workflow or script. Regressions it catches: trusting a branch
* name instead of the head repository, a bot or non-maintainer override, a
* null head.repo passing, the workflow growing a PR checkout or a
* pull_request trigger that would run the PR's own copy.
*/
import { describe, expect, test } from 'bun:test';
import { spawnSync } from 'node:child_process';
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
import { load as loadYaml } from 'js-yaml';
import {
COMMENT_MARKER, MAINTAINERS, OVERRIDE_LABEL, decide, gateMessage, runGate,
type GateClient, type GateEvent, type TimelineEvent,
} from '../../scripts/fix-wave-gate.ts';
const ROOT = join(import.meta.dir, '..', '..');
const FIXTURES = join(ROOT, 'test', 'fixtures', 'fix-wave-gate');
const load = (name: string) => JSON.parse(readFileSync(join(FIXTURES, name), 'utf8')) as GateEvent;
const labeled = (login: string, type: string, id: number): TimelineEvent =>
({ id, event: 'labeled', label: { name: OVERRIDE_LABEL }, actor: { login, type }, created_at: `2026-10-05T0${id}:00:00Z` });
function fakeClient(timeline: TimelineEvent[] = [], comments: string[] = []) {
const calls: string[] = [];
const client: GateClient = {
labelEvents: async () => { calls.push('labelEvents'); return timeline; },
commentBodies: async () => { calls.push('commentBodies'); return comments; },
createComment: async (_pr, body) => { calls.push('createComment'); comments.push(body); },
};
return { client, calls, comments };
}
async function gate(event: GateEvent, client: GateClient, mode: 'gate' | 'comment' = 'gate') {
const lines: string[] = [];
const summary: string[] = [];
const code = await runGate(event, client, { line: s => lines.push(s), summary: s => summary.push(s) }, mode);
return { code, out: lines.join('\n'), summary: summary.join('') };
}
describe('fix-wave gate decision', () => {
test('a fork PR with a GBRA-looking branch name fails with the fix-wave message', async () => {
const { client, calls } = fakeClient();
const r = await gate(load('fork-gbra-branch.opened.json'), client);
expect(r.code).toBe(1);
expect(r.out).not.toContain('stays open');
expect(r.out).toContain('can be merged as it is, after we check every link, command and install step');
expect(r.out).toContain('are taken even when the gain is small');
expect(r.out).toContain('we read as a detailed bug report');
expect(r.out).toContain('close this PR with a link to the PR that landed it');
expect(r.out).toContain('what would change our answer');
expect(r.out).toContain('a failing test');
expect(r.out).toContain('never applies to anyone who has had a pull request taken (merged or rebuilt) in the last 90 days');
expect(r.out).toContain('Contributed by @alice-example');
expect(r.out).toContain('Co-Authored-By:');
expect(r.out).toContain('CONTRIBUTING.md#how-an-outside-pull-request-is-handled');
expect(r.summary).toContain('fail (fork)');
expect(calls).toEqual([]);
});
test('a same-repo head (a GBRA thread capy/* branch) passes without any API call', async () => {
const { client, calls } = fakeClient();
const r = await gate(load('same-repo.synchronize.json'), client);
expect(r.code).toBe(0);
expect(r.summary).toContain('pass (same_repo)');
expect(calls).toEqual([]);
});
test('the override label passes only when a human maintainer applied it, and the run log names who', async () => {
const event = load('fork-override.labeled.json');
const ok = await gate(event, fakeClient([labeled('garrytan', 'User', 1)]).client);
expect(ok.code).toBe(0);
expect(ok.out).toContain('::notice title=Fix-wave gate override::');
expect(ok.out).toContain(`${OVERRIDE_LABEL} applied by @garrytan (User) at 2026-10-05T01:00:00Z (timeline event 1)`);
for (const actor of [['capy-ai[bot]', 'Bot'], ['github-actions[bot]', 'Bot'], ['alice-example', 'User'], ['garrytan[bot]', 'User'], ['garrytan', 'Bot']] as const) {
const r = await gate(event, fakeClient([labeled(actor[0], actor[1], 2)]).client);
expect(r.code, actor[0]).toBe(1);
expect(r.summary).toContain('override_not_by_maintainer');
}
const relabeledByBot = await gate(event, fakeClient([
labeled('garrytan', 'User', 1),
{ id: 2, event: 'unlabeled', label: { name: OVERRIDE_LABEL }, actor: { login: 'garrytan', type: 'User' } },
labeled('capy-ai[bot]', 'Bot', 3),
]).client);
expect(relabeledByBot.code).toBe(1);
const noTimeline = await gate(event, fakeClient([]).client);
expect(noTimeline.code).toBe(1);
});
test('removing the label fails again even though the timeline still shows the old override', () => {
const event = load('fork-override.labeled.json');
event.pull_request!.labels = [];
expect(decide(event, [labeled('garrytan', 'User', 1)])).toMatchObject({ pass: false, reason: 'fork' });
});
test('a null head repository fails closed', async () => {
const r = await gate(load('deleted-fork.synchronize.json'), fakeClient().client);
expect(r.code).toBe(1);
expect(r.summary).toContain('head_repo_missing');
expect(decide({}, []).pass).toBe(false);
});
test('a timeline read failure fails closed', async () => {
const client: GateClient = { ...fakeClient().client, labelEvents: async () => { throw new Error('HTTP 502'); } };
const r = await gate(load('fork-override.labeled.json'), client);
expect(r.code).toBe(1);
expect(r.out).toContain('Could not read the PR timeline');
});
test('the welcome comment posts once on a contributor PR and never on a same-repo PR', async () => {
const fake = fakeClient();
const first = await gate(load('fork-gbra-branch.opened.json'), fake.client, 'comment');
expect(first.code).toBe(0);
expect(fake.comments).toHaveLength(1);
expect(fake.comments[0]).toBe(gateMessage('alice-example'));
expect(fake.comments[0].startsWith(COMMENT_MARKER)).toBe(true);
await gate(load('fork-gbra-branch.opened.json'), fake.client, 'comment');
expect(fake.comments).toHaveLength(1);
const same = fakeClient();
await gate(load('same-repo.synchronize.json'), same.client, 'comment');
expect(same.calls).toEqual([]);
});
test('the maintainer allowlist starts with garrytan and holds no bots', () => {
expect(MAINTAINERS).toEqual(['garrytan']);
for (const m of MAINTAINERS) expect(m).not.toContain('[bot]');
});
});
describe('fix-wave gate workflow', () => {
const text = readFileSync(join(ROOT, '.github', 'workflows', 'fix-wave-gate.yml'), 'utf8');
type Step = { uses?: string; run?: string; with?: Record<string, unknown>; env?: Record<string, string> };
const wf = loadYaml(text) as { on: Record<string, { branches: string[]; types: string[] }>; permissions: unknown; jobs: Record<string, { permissions: Record<string, string>; steps: Step[]; if?: string }> };
test('a PR that edits the workflow or the gate script cannot change its own result', async () => {
// pull_request_target runs the default-branch copy of both files; a pull_request trigger would run the PR's copy.
expect(Object.keys(wf.on)).toEqual(['pull_request_target']);
expect(wf.on.pull_request_target.branches).toEqual(['master']);
expect([...wf.on.pull_request_target.types].sort()).toEqual(['edited', 'labeled', 'opened', 'reopened', 'synchronize', 'unlabeled']);
for (const job of Object.values(wf.jobs)) {
const checkout = job.steps.find(s => s.uses?.startsWith('actions/checkout@'))!;
expect(checkout.with).toEqual({ 'persist-credentials': false, 'sparse-checkout': 'scripts/fix-wave-gate.ts', 'sparse-checkout-cone-mode': false });
}
expect(text).not.toMatch(/pull_request\.head|refs\/pull|head\.sha|head_ref|\bref:/);
for (const job of Object.values(wf.jobs)) for (const s of job.steps) expect(s.run ?? '').not.toContain('${{');
// The decision never reads the PR's files, so a fork PR that rewrites the gate still fails.
expect((await gate(load('fork-edits-gate.synchronize.json'), fakeClient().client)).code).toBe(1);
});
test('permissions are minimal, actions are pinned by SHA and the script needs no dependencies', () => {
expect(wf.permissions).toEqual({});
expect(wf.jobs['contributor-gate'].permissions).toEqual({ contents: 'read', 'pull-requests': 'read' });
expect(wf.jobs['welcome-comment'].permissions).toEqual({ contents: 'read', 'pull-requests': 'write' });
expect(wf.jobs['welcome-comment'].if).toBe("github.event.action == 'opened'");
for (const job of Object.values(wf.jobs)) for (const s of job.steps) if (s.uses) expect(s.uses).toMatch(/@[0-9a-f]{40}$/);
const script = readFileSync(join(ROOT, 'scripts', 'fix-wave-gate.ts'), 'utf8');
const imports = [...script.matchAll(/^import .* from '([^']+)';$/gm)].map(m => m[1]);
expect(imports.every(i => i.startsWith('node:'))).toBe(true);
});
test('the CLI entry decides offline from an event payload', () => {
const run = (name: string) => spawnSync(process.execPath, [join(ROOT, 'scripts', 'fix-wave-gate.ts'), '--event', join(FIXTURES, name)], {
encoding: 'utf8', env: { PATH: process.env.PATH, GITHUB_API_URL: 'http://127.0.0.1:9' },
});
const same = run('same-repo.synchronize.json');
expect(same.status).toBe(0);
expect(same.stdout).toContain('Pass.');
const fork = run('fork-edits-gate.synchronize.json');
expect(fork.status).toBe(1);
expect(fork.stdout).toContain('::error title=Fix-wave gate::');
});
});