Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
14.3 KB
Raw Blame
/**
 * bootstrap status — phase list [D5], install log [B1], runbook skew [C1],
 * support blob [B5], and the CLI reachability membership asserts (#2035
 * precedent, extended per ENG-2 for the bootstrap family).
 */
import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
import { chmodSync, existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { execFileSync } from 'node:child_process';
import { tmpdir } from 'node:os';
import { join } from 'node:path';

import { runBootstrap } from '../src/commands/bootstrap.ts';

import { CLI_ONLY, THIN_CLIENT_REFUSED_COMMANDS } from '../src/cli/main.ts';
import { VERSION } from '../src/version.ts';
import {
  BOOTSTRAP_PHASE_IDS,
  PHASES,
  appendInstallLog,
  readInstallLog,
  installLogPath,
  readRunbookStamp,
  listVerifyRuns,
  statusReport,
} from '../src/core/bootstrap/status.ts';
import { initState, setAnswer, confirm, readBackHash } from '../src/core/bootstrap/interview.ts';
import { writeManifest } from '../src/core/bootstrap/format.ts';
import { loadQuestionBank } from '../src/core/bootstrap/assets.ts';

let tmpParent: string; // GBRAIN_HOME parent (configDir appends .gbrain)
let home: string;
let ws: string;
let prevHome: string | undefined;

beforeAll(() => {
  tmpParent = mkdtempSync(join(tmpdir(), 'gb-status-'));
  home = join(tmpParent, '.gbrain');
  mkdirSync(home, { recursive: true });
  ws = mkdtempSync(join(tmpdir(), 'gb-status-ws-'));
  prevHome = process.env.GBRAIN_HOME;
  process.env.GBRAIN_HOME = tmpParent;
});

afterAll(() => {
  if (prevHome === undefined) delete process.env.GBRAIN_HOME;
  else process.env.GBRAIN_HOME = prevHome;
  rmSync(tmpParent, { recursive: true, force: true });
  rmSync(ws, { recursive: true, force: true });
});

describe('phase list is the single TS source of truth [D5]', () => {
  test('PHASES matches BOOTSTRAP_PHASE_IDS exactly, in order', () => {
    expect(PHASES.map((p) => p.id)).toEqual([...BOOTSTRAP_PHASE_IDS]);
    expect(BOOTSTRAP_PHASE_IDS).toEqual([
      'preflight', 'engine', 'interview', 'render', 'skills', 'wire', 'repo', 'verify',
    ]);
  });

  test('every phase carries a title, a resume hint, and a detector', () => {
    for (const p of PHASES) {
      expect(p.title.length).toBeGreaterThan(0);
      expect(p.resume_hint.length).toBeGreaterThan(0);
      expect(typeof p.detect).toBe('function');
    }
  });

  test('wire hint carries the harness scope rule (Claude Code + opencode consent vs Codex user-global)', () => {
    const wire = PHASES.find((p) => p.id === 'wire');
    expect(wire?.resume_hint).toContain('MCP scope consent applies on Claude Code and opencode');
    expect(wire?.resume_hint).toContain('opencode defaults to user-global');
    expect(wire?.resume_hint).toContain('Codex registrations are always user-global (no scope flag)');
  });
});

describe('CLI reachability membership (#2035 shape, ENG-2)', () => {
  test('bootstrap, hook, and sweep are in CLI_ONLY so dispatch reaches them', () => {
    expect(CLI_ONLY.has('bootstrap')).toBe(true);
    expect(CLI_ONLY.has('hook')).toBe(true);
    expect(CLI_ONLY.has('sweep')).toBe(true);
  });

  test('bootstrap and hook are NOT thin-client refused; sweep IS (local engine only)', () => {
    expect(THIN_CLIENT_REFUSED_COMMANDS.has('bootstrap')).toBe(false);
    expect(THIN_CLIENT_REFUSED_COMMANDS.has('hook')).toBe(false);
    expect(THIN_CLIENT_REFUSED_COMMANDS.has('sweep')).toBe(true);
  });
});

describe('install log [B1]', () => {
  test('append + read round-trip, torn lines skipped, never throws', () => {
    appendInstallLog(home, {
      ts: new Date().toISOString(),
      phase: 'render',
      outcome: 'ok',
      duration_ms: 12,
      binary_version: VERSION,
      workspace: ws,
    });
    // Torn line in the middle must not break the reader.
    writeFileSync(installLogPath(home), '{"half\n', { flag: 'a' });
    appendInstallLog(home, {
      ts: new Date().toISOString(),
      phase: 'wire',
      outcome: 'error',
      duration_ms: 5,
      binary_version: VERSION,
      harness: 'claude-code',
      workspace: ws,
    });
    const entries = readInstallLog(home);
    expect(entries.length).toBe(2);
    expect(entries[0].phase).toBe('render');
    expect(entries[1].phase).toBe('wire');
    expect(entries[1].harness).toBe('claude-code');
  });

  test('reader returns [] for a missing log', () => {
    expect(readInstallLog(join(tmpdir(), 'no-such-gbrain-home'))).toEqual([]);
  });
});

describe('runbook stamp [C1]', () => {
  test('reads the stamp comment; null when absent', () => {
    const dir = mkdtempSync(join(tmpdir(), 'gb-runbook-'));
    expect(readRunbookStamp(dir)).toBeNull();
    writeFileSync(join(dir, 'BOOTSTRAP_FOR_AGENTS.md'), '<!-- gbrain-runbook-stamp: 0.0.1 -->\n# runbook\n');
    expect(readRunbookStamp(dir)).toBe('0.0.1');
    rmSync(dir, { recursive: true, force: true });
  });
});

describe('statusReport detection + support blob [B5]', () => {
  test('fresh workspace: engine/interview/render/verify pending, next action present', async () => {
    const report = await statusReport(ws, { gbrainHomeDir: home });
    const byId = new Map(report.phases.map((p) => [p.id, p]));
    expect(byId.get('engine')!.state).toBe('pending');
    expect(byId.get('interview')!.state).toBe('pending');
    expect(byId.get('render')!.state).toBe('pending');
    expect(byId.get('verify')!.state).toBe('pending');
    expect(report.next).toBeTruthy();
    // The third axis [D-cloud]: installing agents branch on this field.
    expect(['local', 'cloud-sandbox', 'ephemeral-container']).toContain(report.execution_environment);
    expect(report.support.binary_version).toBe(VERSION);
    expect(report.support.engine).toBeNull();
    expect(report.support.harness_registrations).toEqual([]);
  });

  test('artifacts flip phases: config → engine done; confirmed interview → done; manifest → render done', async () => {
    // engine: config file in the sandboxed home.
    writeFileSync(join(home, 'config.json'), JSON.stringify({ engine: 'pglite', database_path: join(home, 'brain.pglite') }));

    // interview: answer every required key, then confirm the read-back hash.
    const bank = loadQuestionBank();
    const required = bank.interviewKeys.filter((k) => bank.questions[k]?.required === true);
    expect(initState(ws).ok).toBe(true);
    for (const key of required) {
      const r = setAnswer(ws, key, `verbatim answer for ${key} with enough substance to be real`);
      expect(r.ok).toBe(true);
    }
    const h = readBackHash(ws);
    if (!h.ok) throw new Error('readBackHash failed');
    expect(confirm(ws, h.hash).ok).toBe(true);

    // render: initialized manifest.
    writeManifest(ws, {
      format_version: 1,
      initialized: true,
      agent_name: 'Testy',
      created_by: 'test',
      created_at: new Date().toISOString(),
      source_id: 'workspace',
    });

    // verify: one persisted failing snapshot → verify phase partial.
    mkdirSync(join(home, 'bootstrap'), { recursive: true });
    writeFileSync(
      join(home, 'bootstrap', 'verify-2026-01-01T00-00-00-000Z.json'),
      JSON.stringify({ ts: '2026-01-01T00:00:00.000Z', ok: false, checks: [{ id: 'roundtrip', ok: false, detail: 'x' }] }),
    );

    const report = await statusReport(ws, { gbrainHomeDir: home });
    const byId = new Map(report.phases.map((p) => [p.id, p]));
    expect(byId.get('engine')!.state).toBe('done');
    expect(byId.get('interview')!.state).toBe('done');
    expect(byId.get('render')!.state).toBe('done');
    expect(byId.get('verify')!.state).toBe('partial');
    expect(report.support.engine).toBe('pglite');
    expect(report.support.last_verify).toEqual({
      ts: '2026-01-01T00:00:00.000Z',
      ok: false,
      checks_failed: ['roundtrip'],
    });
    // listVerifyRuns agrees with the support blob.
    const runs = listVerifyRuns(home);
    expect(runs.length).toBe(1);
    expect(runs[0].ok).toBe(false);
  });

  test('runbook skew surfaces when the stamp disagrees with the binary', async () => {
    writeFileSync(join(ws, 'BOOTSTRAP_FOR_AGENTS.md'), '<!-- gbrain-runbook-stamp: 0.0.1 -->\n');
    const report = await statusReport(ws, { gbrainHomeDir: home });
    expect(report.runbookSkew).toEqual({ runbookStamp: '0.0.1', binaryVersion: VERSION });

    // Matching stamp → no skew reported.
    writeFileSync(join(ws, 'BOOTSTRAP_FOR_AGENTS.md'), `<!-- gbrain-runbook-stamp: ${VERSION} -->\n`);
    const clean = await statusReport(ws, { gbrainHomeDir: home });
    expect(clean.runbookSkew).toBeUndefined();
  });
});

describe('template-door privacy gate (recording gh shim)', () => {
  let tws: string; // template-clone workspace with an origin remote
  let shimDir: string;
  let recordFile: string;
  let savedPath: string | undefined;
  let savedRecord: string | undefined;

  beforeAll(() => {
    tws = mkdtempSync(join(tmpdir(), 'gb-status-tmpl-'));
    execFileSync('git', ['init', '-q', '-b', 'main'], { cwd: tws });
    execFileSync('git', ['remote', 'add', 'origin', 'https://github.com/tester/agent-template.git'], { cwd: tws });
    // Uninitialized template clone — the gate's trigger state [CX2-1].
    writeManifest(tws, {
      format_version: 1,
      initialized: false,
      agent_name: '{{AGENT_NAME}}',
      created_by: 'template',
      created_at: '1970-01-01T00:00:00.000Z',
      source_id: 'workspace',
    });

    shimDir = mkdtempSync(join(tmpdir(), 'gb-status-shim-'));
    recordFile = join(shimDir, 'record.log');
    savedPath = process.env.PATH;
    savedRecord = process.env.GB_FAKE_RECORD;
    process.env.GB_FAKE_RECORD = recordFile;
    // Recording gh shim: answer comes from the GB_FAKE_GH_ANSWER env var.
    writeFileSync(
      join(shimDir, 'gh'),
      `#!/bin/sh
echo "gh $*" >> "$GB_FAKE_RECORD"
case "$GB_FAKE_GH_ANSWER" in
  private) echo "true"; exit 0 ;;
  public) echo "false"; exit 0 ;;
  *) echo "auth error" >&2; exit 4 ;;
esac
`,
    );
    chmodSync(join(shimDir, 'gh'), 0o755);
    process.env.PATH = `${shimDir}:${process.env.PATH ?? ''}`;
  });

  afterAll(() => {
    if (savedPath === undefined) delete process.env.PATH;
    else process.env.PATH = savedPath;
    if (savedRecord === undefined) delete process.env.GB_FAKE_RECORD;
    else process.env.GB_FAKE_RECORD = savedRecord;
    delete process.env.GB_FAKE_GH_ANSWER;
    rmSync(tws, { recursive: true, force: true });
    rmSync(shimDir, { recursive: true, force: true });
  });

  async function captureStatus(): Promise<{ code: number; out: string; err: string }> {
    const origLog = console.log;
    const origErr = console.error;
    let out = '';
    let err = '';
    console.log = (...a: unknown[]) => { out += a.map(String).join(' ') + '\n'; };
    console.error = (...a: unknown[]) => { err += a.map(String).join(' ') + '\n'; };
    try {
      const code = await runBootstrap(['status', '--workspace', tws]);
      return { code, out, err };
    } finally {
      console.log = origLog;
      console.error = origErr;
    }
  }

  test('PUBLIC origin on a template clone → hard fail (exit 1, agent-readable fix)', async () => {
    process.env.GB_FAKE_GH_ANSWER = 'public';
    const report = await statusReport(tws, { gbrainHomeDir: home });
    expect(report.privacy_gate).toEqual({
      verdict: 'public',
      origin: 'https://github.com/tester/agent-template.git',
      detail: expect.stringContaining('PUBLIC'),
    });
    // The probe went through REST (`gh api repos/...`), NEVER `gh repo view`
    // — that command rides GraphQL, which cloud sandbox proxies always 403.
    const recorded = readFileSync(recordFile, 'utf8');
    expect(recorded).toContain('gh api repos/tester/agent-template --jq .private');
    expect(recorded).not.toContain('repo view');

    const r = await captureStatus();
    expect(r.code).toBe(1);
    expect(r.err).toContain('PUBLIC');
    expect(r.err).toContain('private');
  });

  test('[FIX6] `bootstrap render` refuses a PUBLIC origin BEFORE writing identity files', async () => {
    process.env.GB_FAKE_GH_ANSWER = 'public';
    // Precondition: no identity file has been rendered yet.
    expect(existsSync(join(tws, 'SOUL.md'))).toBe(false);

    const origLog = console.log;
    const origErr = console.error;
    let out = '';
    let err = '';
    console.log = (...a: unknown[]) => { out += a.map(String).join(' ') + '\n'; };
    console.error = (...a: unknown[]) => { err += a.map(String).join(' ') + '\n'; };
    let code: number;
    try {
      code = await runBootstrap(['render', '--workspace', tws]);
    } finally {
      console.log = origLog;
      console.error = origErr;
    }
    void out;
    expect(code).toBe(1);
    expect(err).toContain('render refused');
    expect(err).toContain('PUBLIC');
    expect(err).toContain('private');
    // Refused BEFORE any identity file was written.
    expect(existsSync(join(tws, 'SOUL.md'))).toBe(false);
    expect(existsSync(join(tws, 'USER.md'))).toBe(false);
  });

  test('PRIVATE origin → no gate, exit 0', async () => {
    process.env.GB_FAKE_GH_ANSWER = 'private';
    const report = await statusReport(tws, { gbrainHomeDir: home });
    expect(report.privacy_gate).toBeUndefined();
    const r = await captureStatus();
    expect(r.code).toBe(0);
  });

  test('gh unavailable/offline → loud warning, NOT a fail', async () => {
    delete process.env.GB_FAKE_GH_ANSWER; // shim exits 4 (auth error / offline shape)
    const report = await statusReport(tws, { gbrainHomeDir: home });
    expect(report.privacy_gate?.verdict).toBe('unknown');
    const r = await captureStatus();
    expect(r.code).toBe(0);
    expect(r.err).toContain('WARNING');
    expect(r.err).toContain('visibility');
  });

  test('initialized workspace never trips the template-door gate', async () => {
    process.env.GB_FAKE_GH_ANSWER = 'public';
    // ws (outer fixture) is initialized by the earlier detection test and has
    // no origin anyway; flip tws to initialized to isolate the discriminator.
    writeManifest(tws, {
      format_version: 1,
      initialized: true,
      agent_name: 'Testy',
      created_by: 'test',
      created_at: new Date().toISOString(),
      source_id: 'workspace',
    });
    try {
      const report = await statusReport(tws, { gbrainHomeDir: home });
      expect(report.privacy_gate).toBeUndefined();
    } finally {
      writeManifest(tws, {
        format_version: 1,
        initialized: false,
        agent_name: '{{AGENT_NAME}}',
        created_by: 'template',
        created_at: '1970-01-01T00:00:00.000Z',
        source_id: 'workspace',
      });
    }
  });
});