Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Template-repo generator contract [D4, G7, A1, CX2-14].
*
* The "Use this template" tree is generated by src/core/bootstrap/template-repo.ts
* through the SAME render engine the desktop bootstrap uses (one rendering code
* path, two consumers [D4] — a static import of render.ts). Pins:
* byte-determinism (two independent renders identical [CX2-14]), the
* placeholder manifest (initialized:false [CX2-1]), and the README VERSION
* stamp (adopter-skew check [CX-P1.11]).
*
* The README content contract (stamp line, "Use this template" steps,
* stable-only refs, no timestamps) is pinned via the pure
* renderTemplateReadme.
*/
import { describe, expect, test } from 'bun:test';
import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join, resolve } from 'node:path';
import { TEMPLATE_PLACEHOLDER_MANIFEST } from '../src/core/bootstrap/format.ts';
import {
generateTemplateTree,
listTreeFiles,
renderTemplateReadme,
} from '../src/core/bootstrap/template-repo.ts';
const ROOT = resolve(import.meta.dir, '..');
const VERSION = readFileSync(join(ROOT, 'VERSION'), 'utf8').trim();
describe('renderTemplateReadme', () => {
const readme = renderTemplateReadme('1.2.3.4');
test('stamps the version and leaves no {{VERSION}} placeholder', () => {
expect(readme).toContain('<!-- gbrain-template-stamp: 1.2.3.4 -->');
expect(readme).not.toContain('{{VERSION}}');
});
test('carries the Use-this-template instructions with bootstrap status as the first CLI step', () => {
expect(readme).toContain('Use this template');
expect(readme).toContain('gbrain bootstrap status');
expect(readme).toContain('BOOTSTRAP_FOR_AGENTS.md');
// The privacy gate on this door [G7]: status hard-fails on a public origin.
expect(readme.toLowerCase()).toContain('public');
});
test('references only the sanctioned stable distribution ref [C1]', () => {
expect(readme).toContain(
'https://raw.githubusercontent.com/garrytan/gbrain/stable/BOOTSTRAP_FOR_AGENTS.md',
);
expect(readme).toContain('github:garrytan/gbrain#stable');
expect(readme).not.toMatch(/raw\.githubusercontent\.com\/garrytan\/gbrain\/(master|main|v\d)/);
});
test('is deterministic and carries no timestamps [CX2-14]', () => {
expect(renderTemplateReadme('1.2.3.4')).toBe(readme);
// No ISO dates: the only canonical date placeholder in the tree lives in
// agent.json (epoch), never in the README.
expect(readme).not.toMatch(/\d{4}-\d{2}-\d{2}/);
});
test('rejects an empty version', () => {
expect(() => renderTemplateReadme(' ')).toThrow(/non-empty/);
});
});
describe('generateTemplateTree', () => {
test(
'two independent renders are byte-identical [CX2-14]',
async () => {
const dir = mkdtempSync(join(tmpdir(), 'gbrain-template-gen-'));
try {
const a = join(dir, 'a');
const b = join(dir, 'b');
const ra = await generateTemplateTree(a);
const rb = await generateTemplateTree(b);
expect(ra.files.length).toBeGreaterThan(0);
expect(rb.files).toEqual(ra.files);
for (const f of ra.files) {
const ba = readFileSync(join(a, f));
const bb = readFileSync(join(b, f));
expect(bb.equals(ba)).toBe(true);
}
} finally {
rmSync(dir, { recursive: true, force: true });
}
},
);
test(
'writes the canonical placeholder manifest + VERSION-stamped README',
async () => {
const dir = mkdtempSync(join(tmpdir(), 'gbrain-template-gen-'));
try {
const out = join(dir, 'tree');
const res = await generateTemplateTree(out);
expect(res.version).toBe(VERSION);
const manifest = JSON.parse(readFileSync(join(out, 'agent.json'), 'utf8'));
// The template/attach discriminator [CX2-1]: a template clone is
// marked un-initialized; render flips it true on the adopter machine.
expect(manifest).toEqual(TEMPLATE_PLACEHOLDER_MANIFEST as unknown as Record<string, unknown>);
expect(manifest.initialized).toBe(false);
const readme = readFileSync(join(out, 'README.md'), 'utf8');
expect(readme).toContain(`<!-- gbrain-template-stamp: ${VERSION} -->`);
expect(listTreeFiles(out)).toEqual(res.files);
} finally {
rmSync(dir, { recursive: true, force: true });
}
},
);
});