Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
4.3 KB
Raw Blame
/**
 * 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 });
      }
    },
  );
});