Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Contract pin between .github/workflows/release.yml and
* src/core/binary-self-update.ts (#3521).
*
* Binary installs download upgrade assets from the release `latest-stable` names, by the exact
* names expectedAssetName() returns. If the workflow's build matrix or the
* release `files:` list drifts from those names, self-update silently degrades
* to notify-only (`no_asset`) for everyone — this test is the guard.
*/
import { describe, expect, test } from 'bun:test';
import { execFileSync } from 'node:child_process';
import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { EXPECTED_BUILDER_IDS, expectedAssetName } from '../src/core/binary-self-update.ts';
const ROOT = join(import.meta.dir, '..');
const WORKFLOW = readFileSync(join(ROOT, '.github/workflows/release.yml'), 'utf8');
/** Every platform/arch the self-updater can request an asset for. */
const EXPECTED_ASSETS = (
[
['darwin', 'arm64'],
['linux', 'x64'],
] as const
).map(([p, a]) => expectedAssetName(p, a) as string);
describe('release.yml ↔ binary-self-update asset contract', () => {
test('release compiler is covered by the required native runtime matrix', () => {
const build = WORKFLOW.slice(WORKFLOW.indexOf(' build:'), WORKFLOW.indexOf(' release:'));
const compiler = build.match(/bun-version:\s*(\S+)/)?.[1];
expect(compiler).toBe('1.4.4');
const native = readFileSync(join(ROOT, '.github/workflows/native-locks.yml'), 'utf8');
const matrices = [...native.matchAll(/bun:\s*\[([^\]]+)\]/g)];
expect(matrices).toHaveLength(4);
for (const matrix of matrices) {
expect(matrix[1]).toContain(`'${compiler}'`);
}
expect(native).toContain('scripts/native/cli-persistence-smoke.ts');
expect(native).toContain('GBRAIN_TEST_OPENCLAW_BIN:');
expect(native).toContain("job.services.postgres.ports['5432']");
expect(native).toContain('[email protected]');
expect(native).toContain('bun test --timeout=60000 test/openclaw-context-engine-native.serial.test.ts');
expect(build).toContain('codesign --verify --strict --verbose=2');
expect(build.indexOf('codesign --verify')).toBeLessThan(build.indexOf('Smoke-test the compiled binary'));
expect(build).toContain('bun scripts/native/compiled-admin-smoke.ts --binary bin/${{ matrix.artifact }}');
expect(native).toContain('bun scripts/native/compiled-admin-smoke.ts --binary bin/gbrain-native-validation');
});
test('the compiled admin smoke makes a fresh bootstrap token each run instead of committing one', () => {
const smoke = readFileSync(join(ROOT, 'scripts/native/compiled-admin-smoke.ts'), 'utf8');
expect(smoke).not.toMatch(/GBRAIN_ADMIN_BOOTSTRAP_TOKEN:\s*['"`]/);
expect(smoke).toMatch(/const bootstrapToken = randomBytes\(\d+\)\.toString\('hex'\);/);
expect(smoke).toContain('GBRAIN_ADMIN_BOOTSTRAP_TOKEN: bootstrapToken,');
});
test('workflow build matrix produces exactly the assets the updater requests', () => {
const artifacts = [...WORKFLOW.matchAll(/artifact:\s*(\S+)/g)].map((m) => m[1]).sort();
expect(artifacts).toEqual([...EXPECTED_ASSETS].sort());
});
test('every expected asset is attached to the release', () => {
for (const name of EXPECTED_ASSETS) {
// download-artifact unpacks to artifacts/<name>/<name>
expect(WORKFLOW).toContain(`artifacts/${name}/${name}`);
}
});
test('idempotency completeness check names every expected asset', () => {
// The version job only skips when the existing release carries ALL assets;
// its sorted-join comparison string must stay in sync with the matrix.
expect(WORKFLOW).toContain([...EXPECTED_ASSETS].sort().join(','));
});
test('release tag derives from the VERSION file, v-prefixed', () => {
expect(WORKFLOW).toContain('< VERSION');
expect(WORKFLOW).toMatch(/tag_name: v\$\{\{ needs\.version\.outputs\.version \}\}/);
});
test('missing binaries fail the release instead of publishing assetless', () => {
expect(WORKFLOW).toContain('fail_on_unmatched_files: true');
});
test('contents:write is scoped to the release job, not the whole workflow', () => {
const topLevel = WORKFLOW.slice(0, WORKFLOW.indexOf('jobs:'));
expect(topLevel).toContain('contents: read');
expect(topLevel).not.toContain('contents: write');
});
test('build attests provenance for the compiled binary (self-update integrity depends on it)', () => {
// binary-self-update verifies the downloaded asset against this attestation
// (verifyIntegrity). Removing the attest step would fail-close every fleet
// self-update (integrity_unavailable) with CI still green — this is the pin.
expect(WORKFLOW).toContain('attest-build-provenance');
expect(WORKFLOW).toMatch(/subject-path:\s*bin\/\$\{\{ matrix\.artifact \}\}/);
});
test('expected builder ids name this workflow file on a trusted ref', () => {
// verifyIntegrity accepts only attestations whose builder id is exactly
// release.yml@<trusted ref>. If the workflow file is renamed or the ref
// scheme changes, this test forces the constant to move in lockstep.
for (const id of EXPECTED_BUILDER_IDS) {
expect(id).toContain('/.github/workflows/release.yml@');
const ref = id.split('@')[1]!;
expect(ref.startsWith('refs/')).toBe(true);
}
// The workflow this repo actually ships from is the one the ids name.
expect(EXPECTED_BUILDER_IDS.some((id) => id.endsWith('@refs/heads/master'))).toBe(true);
});
test('release builds the admin UI fresh from source before compiling', () => {
// Supply-chain pin: the distributed binary's admin bundle must come from
// admin/src (built in the release job), never from committed admin/dist
// bytes. Deleting this step would silently re-trust the committed bundle.
expect(WORKFLOW).toContain('bun run build:admin');
expect(WORKFLOW).toMatch(/cd admin && bun install --frozen-lockfile/);
// Cache key covers the admin lockfile so the fresh build is reproducible.
expect(WORKFLOW).toContain("hashFiles('bun.lock', 'admin/bun.lock')");
// Ordering: the admin build must run BEFORE the compile that embeds it.
const adminIdx = WORKFLOW.indexOf('bun run build:admin');
const compileIdx = WORKFLOW.indexOf('bun build --compile');
expect(adminIdx).toBeGreaterThan(-1);
expect(compileIdx).toBeGreaterThan(-1);
expect(adminIdx).toBeLessThan(compileIdx);
});
test('template-repo push keeps the PAT out of argv (askpass, not URL-embedded)', () => {
// The token must never ride the git command line: no
// `https://x-access-token:${TEMPLATE_REPO_PAT}@...` remote URLs.
expect(WORKFLOW).not.toContain('x-access-token:${TEMPLATE_REPO_PAT}@');
expect(WORKFLOW).not.toMatch(/git push[^\n]*TEMPLATE_REPO_PAT/);
// Credential travels out-of-band via a one-shot askpass reading env.
expect(WORKFLOW).toContain('GIT_ASKPASS="$ASKPASS" GIT_TERMINAL_PROMPT=0');
// Force-push semantics preserved (history-less template publish).
expect(WORKFLOW).toMatch(/git push --force "https:\/\/github\.com\/\$\{TEMPLATE_REPO\}\.git" HEAD:main/);
});
});
describe('scripts/changelog-entry.sh', () => {
const FIXTURE = `# Changelog
## [0.42.67.0] - 2026-07-28
Release summary line.
### Fixed
- top entry fix
## [0.42.6] - 2026-07-27
### Added
- historical 3-segment entry
`;
function run(version: string): { out: string; code: number } {
const dir = mkdtempSync(join(tmpdir(), 'gbrain-chlog-'));
const file = join(dir, 'CHANGELOG.md');
writeFileSync(file, FIXTURE);
try {
const out = execFileSync('bash', [join(ROOT, 'scripts/changelog-entry.sh'), version, file], {
encoding: 'utf-8',
});
return { out, code: 0 };
} catch (e: any) {
return { out: String(e.stdout ?? ''), code: e.status ?? 1 };
} finally {
rmSync(dir, { recursive: true, force: true });
}
}
test('extracts exactly the requested entry, header excluded', () => {
const { out, code } = run('0.42.67.0');
expect(code).toBe(0);
expect(out).toContain('top entry fix');
expect(out).not.toContain('## [0.42.67.0]');
expect(out).not.toContain('historical 3-segment entry');
});
test('extracts a non-top (historical 3-segment) entry', () => {
const { out, code } = run('0.42.6');
expect(code).toBe(0);
expect(out).toContain('historical 3-segment entry');
expect(out).not.toContain('top entry fix');
});
test('exits non-zero for a version with no entry', () => {
expect(run('9.9.9.9').code).not.toBe(0);
});
test('a version that is a string prefix of another does not false-match', () => {
// "0.42.67" is a prefix of "0.42.67.0" but has no entry of its own.
expect(run('0.42.67').code).not.toBe(0);
});
});
describe('scripts/changelog-entry.sh --pr-list', () => {
function git(cwd: string, ...args: string[]): string {
return execFileSync('git', args, { cwd, encoding: 'utf-8' });
}
function commit(repo: string, subject: string, files: Record<string, string | null>): void {
for (const [path, text] of Object.entries(files)) {
if (text === null) git(repo, 'rm', '-q', path);
else {
mkdirSync(join(repo, dirname(path)), { recursive: true });
writeFileSync(join(repo, path), text);
git(repo, 'add', path);
}
}
git(repo, 'commit', '-q', '-m', subject);
}
const section = (v: string, body: string) => `# Changelog\n\n## [${v}] - 2026-11-15\n\n${body}\n`;
function fixture(): string {
const repo = mkdtempSync(join(tmpdir(), 'gbrain-prlist-'));
git(repo, 'init', '-q', '-b', 'master');
git(repo, 'config', 'user.email', '[email protected]');
git(repo, 'config', 'user.name', 't');
git(repo, 'config', 'commit.gpgsign', 'false');
commit(repo, 'v0.1.0.0 release (#1)', { VERSION: '0.1.0.0\n', 'CHANGELOG.md': section('0.1.0.0', 'First.'), 'changelog.d/README.md': 'How fragments work.\n' });
git(repo, 'tag', 'v0.1.0.0');
commit(repo, 'Sync is faster (#11)', { 'changelog.d/b-beta.md': '**Sync is faster.**\n\n### Changed\n- beta\n' });
commit(repo, 'Search finds old pages again (#12)', { 'changelog.d/a-alpha.md': '---\nimportant: regression\n---\n**Search finds old pages again (#12).**\n\n### Fixed\n- alpha\n' });
return repo;
}
function run(repo: string, ...args: string[]): string {
return execFileSync('bash', [join(ROOT, 'scripts/changelog-entry.sh'), ...args], { cwd: repo, encoding: 'utf-8' });
}
test('opens the body with one line per folded fragment, in fold order, each with the PR that added it', () => {
const repo = fixture();
try {
commit(repo, 'v0.1.1.0 release (#13)', { VERSION: '0.1.1.0\n', 'CHANGELOG.md': section('0.1.1.0', 'Folded text.'), 'changelog.d/a-alpha.md': null, 'changelog.d/b-beta.md': null });
expect(run(repo, '--pr-list', '0.1.1.0')).toBe('- Search finds old pages again (#12)\n- Sync is faster (#11)\n\n\nFolded text.\n');
expect(run(repo, '0.1.1.0')).toBe('\nFolded text.\n');
} finally {
rmSync(repo, { recursive: true, force: true });
}
});
test('a release that never published is listed in the next one, a commit with no PR number gets a bare line, and a headline that cites another PR prints every number once in one bracket', () => {
const repo = fixture();
try {
commit(repo, 'v0.1.1.0 release (#13)', { VERSION: '0.1.1.0\n', 'CHANGELOG.md': section('0.1.1.0', 'Unpublished.'), 'changelog.d/a-alpha.md': null, 'changelog.d/b-beta.md': null });
commit(repo, 'Direct fix', { 'changelog.d/c-gamma.md': '**The test passes after a release.**\n' });
commit(repo, 'Note the test fix (#14)', { 'changelog.d/d-delta.md': '**The notice test keeps passing after a release (#9).**\n' });
commit(repo, 'v0.1.2.0 release (#15)', { VERSION: '0.1.2.0\n', 'CHANGELOG.md': section('0.1.2.0', 'Second.'), 'changelog.d/c-gamma.md': null, 'changelog.d/d-delta.md': null });
expect(run(repo, '--pr-list', '0.1.2.0')).toBe('- Search finds old pages again (#12)\n- Sync is faster (#11)\n- The test passes after a release\n- The notice test keeps passing after a release (#9, #14)\n\n\nSecond.\n');
} finally {
rmSync(repo, { recursive: true, force: true });
}
});
test('a headline that ends in an internal issue code drops the code and keeps the pull request bracket', () => {
const repo = fixture();
try {
commit(repo, 'Doctor names the fix (GST-2731) (#21)', { 'changelog.d/e-eps.md': '**Doctor names the fix (GST-2731).**\n' });
commit(repo, 'Direct note', { 'changelog.d/f-zeta.md': '**Import keeps calls apart (ABC-7)**\n' });
commit(repo, 'Release notes cite issues (#22)', { 'changelog.d/g-eta.md': '**Release notes keep the (ENG-5) code they quote, and PROJECT-9 codes too (TOOLONG-3).**\n' });
commit(repo, 'v0.1.1.0 release (#23)', { VERSION: '0.1.1.0\n', 'CHANGELOG.md': section('0.1.1.0', 'Folded.'), 'changelog.d/a-alpha.md': null, 'changelog.d/b-beta.md': null,
'changelog.d/e-eps.md': null, 'changelog.d/f-zeta.md': null, 'changelog.d/g-eta.md': null });
expect(run(repo, '--pr-list', '0.1.1.0')).toBe('- Search finds old pages again (#12)\n- Sync is faster (#11)\n- Doctor names the fix (#21)\n- Import keeps calls apart\n'
+ '- Release notes keep the (ENG-5) code they quote, and PROJECT-9 codes too (TOOLONG-3) (#22)\n\n\nFolded.\n');
} finally {
rmSync(repo, { recursive: true, force: true });
}
});
test('a headline with body text after its closing ** on the same line prints the headline alone', () => {
const repo = fixture();
try {
commit(repo, 'Purged pages stay purged (#31)', { 'changelog.d/h-theta.md': '---\nimportant: security\n---\n**A purged page stays purged after a restore.** When an owner purges a page, more text follows **here**.\n' });
commit(repo, 'v0.1.1.0 release (#32)', { VERSION: '0.1.1.0\n', 'CHANGELOG.md': section('0.1.1.0', 'Folded.'), 'changelog.d/a-alpha.md': null, 'changelog.d/b-beta.md': null, 'changelog.d/h-theta.md': null });
expect(run(repo, '--pr-list', '0.1.1.0')).toBe('- Search finds old pages again (#12)\n- Sync is faster (#11)\n- A purged page stays purged after a restore (#31)\n\n\nFolded.\n');
} finally {
rmSync(repo, { recursive: true, force: true });
}
});
test('with no earlier release tag the body is the plain entry', () => {
const repo = fixture();
try {
git(repo, 'tag', '-d', 'v0.1.0.0');
commit(repo, 'v0.1.1.0 release (#13)', { VERSION: '0.1.1.0\n', 'CHANGELOG.md': section('0.1.1.0', 'Folded text.'), 'changelog.d/a-alpha.md': null, 'changelog.d/b-beta.md': null });
expect(run(repo, '--pr-list', '0.1.1.0')).toBe('\nFolded text.\n');
expect(() => run(repo, '--pr-list', '9.9.9.9')).toThrow();
} finally {
rmSync(repo, { recursive: true, force: true });
}
});
});
describe('release.yml publish-template skip is visible (D-10)', () => {
test('an empty TEMPLATE_REPO_PAT warns with the owner-only fix and writes a step summary', async () => {
const { load } = await import('js-yaml');
const wf = load(WORKFLOW) as { jobs: Record<string, { steps: Array<{ id?: string; run?: string }> }> };
const gate = wf.jobs['publish-template']!.steps.find(s => s.id === 'gate')!.run!;
const dir = mkdtempSync(join(tmpdir(), 'gbrain-publish-template-gate-'));
try {
const output = join(dir, 'output');
const summary = join(dir, 'summary');
writeFileSync(output, '');
const stdout = execFileSync('bash', ['-euo', 'pipefail', '-c', gate], {
cwd: ROOT, encoding: 'utf8',
env: { PATH: process.env.PATH, TEMPLATE_REPO_PAT: '', TEMPLATE_REPO: 'owner/template-example', GITHUB_OUTPUT: output, GITHUB_STEP_SUMMARY: summary },
});
expect(readFileSync(output, 'utf8')).toContain('publish=false');
expect(stdout).toContain('::warning::Agent template NOT published to owner/template-example');
expect(stdout).toContain('Fix (owner-only): gh secret set TEMPLATE_REPO_PAT');
expect(readFileSync(summary, 'utf8')).toContain('## Agent template not published');
expect(stdout).not.toContain('SKIP:');
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
});
describe('which release GitHub calls Latest', () => {
test('release.yml publishes every batch release as a pre-release that never becomes Latest', () => {
const step = WORKFLOW.slice(WORKFLOW.indexOf('- name: Create release'), WORKFLOW.indexOf('- name: Advance latest-stable'));
expect(step).toMatch(/^\s+prerelease: true$/m);
expect(step).toMatch(/^\s+make_latest: 'false'$/m);
});
test('a hand re-run that repairs the current stable release refuses instead of turning it back into a pre-release', () => {
const job = WORKFLOW.slice(WORKFLOW.indexOf('\n release:\n'));
const start = job.indexOf('- name: Refuse to republish the current stable release');
expect(start).toBeGreaterThan(-1);
expect(start).toBeLessThan(job.indexOf('- name: Create release'));
const step = job.slice(start, job.indexOf('- name: Create release'));
expect(step).toContain('RELEASE_SHA: ${{ needs.ci-gate.outputs.sha }}');
const script = step.slice(step.indexOf('run: |') + 'run: |'.length).split('\n').map(l => l.replace(/^ {10}/, '')).join('\n');
const dir = mkdtempSync(join(tmpdir(), 'release-stable-guard-'));
try {
writeFileSync(join(dir, 'git'), '#!/bin/sh\n[ "$1 $2 $3" = "ls-remote origin refs/tags/stable^{}" ] || exit 9\nprintf "%s\\trefs/tags/stable^{}\\n" "$STABLE_SHA"\n', { mode: 0o755 });
const runWith = (stable: string) => {
try {
return { code: 0, out: execFileSync('bash', ['-c', script], { env: { PATH: `${dir}:/usr/bin:/bin`, RELEASE_SHA: 'a'.repeat(40), RELEASE_VERSION: '0.60.722.0', STABLE_SHA: stable }, encoding: 'utf8', stdio: 'pipe' }) };
} catch (e) {
const err = e as { status: number; stdout: string; stderr: string };
return { code: err.status, out: err.stdout + err.stderr };
}
};
const stable = runWith('a'.repeat(40));
expect(stable.code).toBe(1);
expect(stable.out).toContain('v0.60.722.0 is the current stable release');
expect(runWith('b'.repeat(40))).toEqual({ code: 0, out: '' });
expect(runWith('')).toEqual({ code: 0, out: '' });
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
test('no workflow reads releases/latest, and the macOS signature check takes its tag from latest-stable', () => {
const dir = join(ROOT, '.github/workflows');
for (const file of readdirSync(dir)) {
const body = readFileSync(join(dir, file), 'utf8').split('\n').filter(l => !l.trimStart().startsWith('#')).join('\n');
expect({ file, reads: body.includes('releases/latest') }).toEqual({ file, reads: false });
}
const mac = readFileSync(join(dir, 'macos-validation.yml'), 'utf8');
expect(mac).toContain('https://raw.githubusercontent.com/garrytan/gbrain/latest-stable/VERSION');
});
});