Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
25.4 KB
Raw Blame
/**
 * scripts/check-public-surface.ts against throwaway git repositories: a base branch, then a head commit that drops a
 * manifest entry, adds deprecation records or behaviour-change rows, or changes a CLI golden. Each case shows the
 * refusal and the change that clears it.
 */
import { afterAll, describe, expect, test } from 'bun:test';
import { spawnSync } from 'node:child_process';
import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { main } from '../../scripts/check-public-surface.ts';
import { buildSurface, main as buildMain, MANIFEST } from '../../scripts/build-public-surface.ts';

const roots: string[] = [];
afterAll(() => { for (const r of roots) rmSync(r, { recursive: true, force: true }); });

const TODAY = '2026-11-16';
const manifest = (over: Record<string, unknown> = {}) => JSON.stringify({
  version: 1,
  'cli-command': ['gbrain search'],
  'cli-flag': ['gbrain search --limit', 'gbrain search --match'],
  'mcp-tool': ['search'],
  'mcp-param': ['search.limit'],
  'config-key': ['search.mode'],
  'exit-code': { not_found: 4 },
  ...over,
}, null, 2) + '\n';

function git(root: string, ...args: string[]) {
  const r = spawnSync('git', args, { cwd: root, encoding: 'utf8' });
  if (r.status !== 0) throw new Error(`git ${args.join(' ')}: ${r.stderr}`);
}
function write(root: string, files: Record<string, string>) {
  for (const [path, text] of Object.entries(files)) {
    mkdirSync(dirname(join(root, path)), { recursive: true });
    writeFileSync(join(root, path), text);
  }
}
function repo(base: Record<string, string>, head: Record<string, string>): string {
  const root = mkdtempSync(join(tmpdir(), 'gbrain-public-surface-'));
  roots.push(root);
  git(root, 'init', '-q', '-b', 'base');
  git(root, 'config', 'user.email', '[email protected]');
  git(root, 'config', 'user.name', 'test');
  write(root, { [MANIFEST]: manifest(), 'README.md': 'x\n', ...base });
  git(root, 'add', '-A');
  git(root, 'commit', '-q', '-m', 'base');
  git(root, 'checkout', '-q', '-b', 'head');
  write(root, head);
  git(root, 'add', '-A');
  git(root, 'commit', '-q', '--allow-empty', '-m', 'head');
  return root;
}
function run(root: string, env: Record<string, string> = {}): { code: number; out: string } {
  const lines: string[] = [];
  const code = main({ cwd: root, env: { GBRAIN_SURFACE_BASE_REF: 'base', GBRAIN_SURFACE_TODAY: TODAY, ...env }, log: (l) => lines.push(l) });
  return { code, out: lines.join('\n') };
}
function tagStable(root: string, stableManifest: string | null) {
  git(root, 'checkout', '-q', '-b', 'stable-release', 'base');
  if (stableManifest === null) git(root, 'rm', '-q', MANIFEST);
  else write(root, { [MANIFEST]: stableManifest });
  git(root, 'add', '-A');
  git(root, 'commit', '-q', '--allow-empty', '-m', 'stable');
  git(root, 'tag', 'stable');
  git(root, 'checkout', '-q', 'head');
}
function shallowClone(origin: string, branch: string): string {
  const clone = mkdtempSync(join(tmpdir(), 'gbrain-public-surface-clone-'));
  roots.push(clone);
  git(clone, 'clone', '-q', '--depth=1', '--no-tags', '--branch', branch, `file://${origin}`, '.');
  git(clone, 'fetch', '-q', '--no-tags', '--depth=1', 'origin', '+refs/heads/base:refs/remotes/origin/base');
  return clone;
}
function mergeClone(head: Record<string, string>): string {
  const origin = repo({}, head);
  tagStable(origin, manifest());
  git(origin, 'checkout', '-q', 'base');
  write(origin, { 'README.md': 'base moved\n' });
  git(origin, 'commit', '-qam', 'base moves on');
  git(origin, 'checkout', '-q', '-b', 'merge', 'base');
  git(origin, 'merge', '-q', '--no-ff', '--no-edit', 'head');
  return shallowClone(origin, 'merge');
}
function hangOrigin(clone: string) {
  const script = join(clone, '..', `${clone.split('/').pop()}-hang.sh`);
  writeFileSync(script, '#!/bin/sh\nexec sleep 10\n');
  chmodSync(script, 0o755);
  roots.push(script);
  git(clone, 'config', 'remote.origin.uploadpack', script);
}
const row = (front: string, text = 'Text.') => `---\n${front}\n---\n${text}\n`;
const record = (surface: string, name: string, removeAfter: string) => `---\nsurface: ${surface}\nname: ${name}\nowner: alice-example\nremove_after: ${removeAfter}\n---\nUse the new one.\n`;

describe('dropped manifest entries', () => {
  test('a flag removed with no record is refused', () => {
    const r = run(repo({}, { [MANIFEST]: manifest({ 'cli-flag': ['gbrain search --match'] }) }));
    expect(r.code).toBe(1);
    expect(r.out).toContain('cli-flag `gbrain search --limit` is removed or changed with no deprecations.d/<id>.md naming it');
  });

  test('a record whose remove_after has not come refuses the removal; a matured one allows it', () => {
    const head = { [MANIFEST]: manifest({ 'cli-flag': ['gbrain search --match'] }) };
    const early = run(repo({ 'deprecations.d/search_limit_flag_1234.md': record('cli-flag', 'gbrain search --limit', '2026-11-20') }, head));
    expect(early.code).toBe(1);
    expect(early.out).toContain('is removed before its record deprecations.d/search_limit_flag_1234.md allows it (remove_after 2026-11-20)');
    const due = run(repo({ 'deprecations.d/search_limit_flag_1234.md': record('cli-flag', 'gbrain search --limit', '2026-11-16') }, head));
    expect(due.code).toBe(0);
  });

  test('an exit code whose number changed counts as a removal', () => {
    const r = run(repo({}, { [MANIFEST]: manifest({ 'exit-code': { not_found: 1 } }) }));
    expect(r.code).toBe(1);
    expect(r.out).toContain('exit-code `not_found` is removed or changed');
  });

  test('adding entries is allowed, and a base with no manifest skips the removal check', () => {
    expect(run(repo({}, { [MANIFEST]: manifest({ 'mcp-tool': ['search', 'think'] }) })).code).toBe(0);
    const root = repo({}, {});
    git(root, 'checkout', '-q', 'base');
    git(root, 'rm', '-q', MANIFEST);
    git(root, 'commit', '-q', '-m', 'no manifest');
    git(root, 'checkout', '-q', '-b', 'head-after', 'base');
    write(root, { [MANIFEST]: manifest() });
    git(root, 'add', '-A');
    git(root, 'commit', '-q', '-m', 'head adds the manifest');
    const r = run(root);
    expect(r.code).toBe(0);
    expect(r.out).toContain('has no docs/contracts/public-surface.json yet');
  });

  test('a matured cli-command or mcp-tool record also covers the flags or parameters the removal drops', () => {
    const gone = { [MANIFEST]: manifest({ 'cli-command': [], 'cli-flag': [], 'mcp-tool': [], 'mcp-param': [] }) };
    const r = run(repo({
      'deprecations.d/search_command_1234.md': record('cli-command', 'gbrain search', '2026-11-10'),
      'deprecations.d/search_tool_1234.md': record('mcp-tool', 'search', '2026-11-10'),
    }, gone));
    expect(r.out).not.toContain('FAIL');
    expect(r.code).toBe(0);
  });
});

describe('removals the promise does not cover', () => {
  test('a new kind: breaking row with exception: security or data-loss lets a removal through', () => {
    for (const exception of ['security', 'data-loss']) {
      const r = run(repo({}, { [MANIFEST]: manifest({ 'mcp-tool': [] }), 'behavior-changes.d/drop_search_1234.md': row(`kind: breaking\nexception: ${exception}`) }));
      expect(r.out).not.toContain('FAIL');
      expect(r.code).toBe(0);
    }
  });

  test('an entry that never reached stable can go with no record; one on stable cannot', () => {
    const base = { [MANIFEST]: manifest({ 'mcp-tool': ['search', 'think'], 'exit-code': { not_found: 5 } }) };
    const unreleased = repo(base, { [MANIFEST]: manifest() });
    tagStable(unreleased, manifest());
    const ok = run(unreleased);
    expect(ok.out).not.toContain('FAIL');
    expect(ok.code).toBe(0);
    const released = repo(base, { [MANIFEST]: manifest({ 'mcp-tool': [] }) });
    tagStable(released, manifest());
    const r = run(released);
    expect(r.code).toBe(1);
    expect(r.out).toContain('mcp-tool `search` is removed or changed with no deprecations.d/<id>.md naming it');
    expect(r.out).not.toContain('mcp-tool `think`');
    expect(r.out).not.toContain('exit-code');
  });

  test('exception: revert lets a removal through while no stable manifest can be read, and says why', () => {
    const head = { [MANIFEST]: manifest({ 'mcp-tool': [] }), 'behavior-changes.d/revert_search_1234.md': row('kind: breaking\nexception: revert', 'Reverts #9999.') };
    const untagged = run(repo({}, head));
    expect(untagged.code).toBe(0);
    expect(untagged.out).toContain('stable ref refs/tags/stable is unavailable (a shallow clone or a missing tag), so every entry counts as on stable');
    const root = repo({}, head);
    tagStable(root, null);
    const noManifest = run(root);
    expect(noManifest.code).toBe(0);
    expect(noManifest.out).toContain('stable (refs/tags/stable) has no docs/contracts/public-surface.json yet, so every entry counts as on stable');
    const plain = run(repo({}, { [MANIFEST]: manifest({ 'mcp-tool': [] }) }));
    expect(plain.code).toBe(1);
  });

  test('exception: revert does not cover an entry that is on stable', () => {
    const root = repo({}, { [MANIFEST]: manifest({ 'mcp-tool': [] }), 'behavior-changes.d/revert_search_1234.md': row('kind: breaking\nexception: revert', 'Reverts #9999.') });
    tagStable(root, manifest());
    const r = run(root);
    expect(r.code).toBe(1);
    expect(r.out).toContain('it is on stable, so exception: revert does not cover it');
  });

  test('a revert row names the pull request it reverts', () => {
    const r = run(repo({}, { 'behavior-changes.d/revert_search_1234.md': row('kind: breaking\nexception: revert', 'Undo the change.') }));
    expect(r.code).toBe(1);
    expect(r.out).toContain('exception: revert needs the notice text to name the pull request it reverts (#<number>)');
  });
});

describe('the base it compares with', () => {
  test('changes the base made after the branch point are not this branch\'s (an added tool, a release that moved a row)', () => {
    const root = repo({ 'behavior-changes.d/old_row_1234.md': 'Plain text.\n' }, {});
    git(root, 'checkout', '-q', 'base');
    write(root, { [MANIFEST]: manifest({ 'mcp-tool': ['search', 'think'] }) });
    git(root, 'rm', '-q', 'behavior-changes.d/old_row_1234.md');
    git(root, 'commit', '-qam', 'base moves on');
    git(root, 'checkout', '-q', 'head');
    const r = run(root);
    expect(r.out).not.toContain('FAIL');
    expect(r.code).toBe(0);
  });

  test('a shallow CI clone is deepened until it has a merge base', () => {
    const origin = repo({}, {});
    git(origin, 'checkout', '-q', 'base');
    write(origin, { [MANIFEST]: manifest({ 'mcp-tool': ['search', 'think'] }) });
    git(origin, 'commit', '-qam', 'base adds think');
    const clone = mkdtempSync(join(tmpdir(), 'gbrain-public-surface-clone-'));
    roots.push(clone);
    git(clone, 'clone', '-q', '--depth=1', '--branch', 'head', `file://${origin}`, '.');
    git(clone, 'fetch', '-q', '--no-tags', '--depth=1', 'origin', '+refs/heads/base:refs/remotes/origin/base');
    const r = run(clone, { GBRAIN_SURFACE_BASE_REF: 'origin/base', CI: 'true' });
    expect(r.out).not.toContain('FAIL');
    expect(r.code).toBe(0);
  });

  test('a shallow clone is deepened with a blob filter, the one GitHub serves to a shallow clone that is not partial', () => {
    const origin = repo({}, {});
    git(origin, 'config', 'uploadpack.allowFilter', 'true');
    git(origin, 'config', 'uploadpackfilter.allow', 'false');
    git(origin, 'config', 'uploadpackfilter.blob:none.allow', 'true');
    git(origin, 'commit', '-q', '--allow-empty', '-m', 'head after the base merge');
    git(origin, 'checkout', '-q', 'base');
    write(origin, { [MANIFEST]: manifest({ 'mcp-tool': ['search', 'think'] }) });
    git(origin, 'commit', '-qam', 'base adds think');
    const clone = mkdtempSync(join(tmpdir(), 'gbrain-public-surface-clone-'));
    roots.push(clone);
    git(clone, 'clone', '-q', '--depth=1', '--no-tags', '--branch', 'head', `file://${origin}`, '.');
    git(clone, 'fetch', '-q', '--no-tags', '--depth=1', 'origin', '+refs/heads/base:refs/remotes/origin/base');
    const r = run(clone, { GBRAIN_SURFACE_BASE_REF: 'origin/base', CI: 'true' });
    expect(r.out).not.toContain('FAIL');
    expect(r.code).toBe(0);
  });

  test('a deepen fetch that fails prints git\'s own error', () => {
    const origin = repo({}, {});
    git(origin, 'commit', '-q', '--allow-empty', '-m', 'head after the base merge');
    const clone = shallowClone(origin, 'head');
    git(clone, 'remote', 'set-url', 'origin', join(clone, 'no-such-remote'));
    const r = run(clone, { GBRAIN_SURFACE_BASE_REF: 'origin/base', CI: 'true' });
    expect(r.code).toBe(1);
    expect(r.out).toContain('no merge base between HEAD and origin/base');
    expect(r.out).toMatch(/git: .*(does not appear to be a git repository|not found|No such file)/);
  });

  test('a base manifest that cannot be read fails under CI instead of counting as missing, and skips locally', () => {
    const origin = repo({}, { [MANIFEST]: manifest({ 'mcp-tool': [] }) });
    git(origin, 'config', 'uploadpack.allowFilter', 'true');
    const clone = mkdtempSync(join(tmpdir(), 'gbrain-public-surface-clone-'));
    roots.push(clone);
    git(clone, 'clone', '-q', '--filter=blob:none', '--no-tags', '--branch', 'head', `file://${origin}`, '.');
    git(clone, 'fetch', '-q', '--no-tags', 'origin', '+refs/heads/base:refs/remotes/origin/base');
    git(clone, 'remote', 'set-url', 'origin', join(clone, 'no-such-remote'));
    const ci = run(clone, { GBRAIN_SURFACE_BASE_REF: 'origin/base', CI: 'true' });
    expect(ci.code).toBe(1);
    expect(ci.out).toContain(`FAIL: check-public-surface: ${MANIFEST} could not be read at origin/base's merge base`);
    expect(ci.out).toMatch(/\ngit: \S/);
    const local = run(clone, { GBRAIN_SURFACE_BASE_REF: 'origin/base' });
    expect(local.code).toBe(0);
    expect(local.out).toContain(`GBRAIN_CHECK_SKIPPED: ${MANIFEST} could not be read at the merge base`);
  });

  test('a shallow pull-request merge commit whose parent is the base tip needs no fetch', () => {
    const origin = repo({}, { [MANIFEST]: manifest({ 'mcp-tool': ['search', 'think'] }) });
    git(origin, 'checkout', '-q', 'base');
    write(origin, { 'README.md': 'base moved\n' });
    git(origin, 'commit', '-qam', 'base moves on');
    git(origin, 'checkout', '-q', '-b', 'merge', 'base');
    git(origin, 'merge', '-q', '--no-ff', '--no-edit', 'head');
    const clone = mkdtempSync(join(tmpdir(), 'gbrain-public-surface-clone-'));
    roots.push(clone);
    git(clone, 'clone', '-q', '--depth=1', '--branch', 'merge', `file://${origin}`, '.');
    git(clone, 'fetch', '-q', '--no-tags', '--depth=1', 'origin', '+refs/heads/base:refs/remotes/origin/base');
    git(clone, 'remote', 'set-url', 'origin', join(clone, 'no-such-remote'));
    const r = run(clone, { GBRAIN_SURFACE_BASE_REF: 'origin/base', CI: 'true' });
    expect(r.out).not.toContain('FAIL');
    expect(r.code).toBe(0);
  });

  test('a shallow CI clone with no tags fetches the stable tag, so an entry stable never had can go', () => {
    const origin = repo({ [MANIFEST]: manifest({ 'mcp-tool': ['search', 'think'] }) }, { [MANIFEST]: manifest() });
    tagStable(origin, manifest());
    const r = run(shallowClone(origin, 'head'), { GBRAIN_SURFACE_BASE_REF: 'origin/base', CI: 'true' });
    expect(r.out).not.toContain('FAIL');
    expect(r.code).toBe(0);
  });

  test('a stable tag that cannot be fetched fails loudly under CI and falls back locally', () => {
    const clone = mergeClone({ [MANIFEST]: manifest({ 'mcp-tool': [] }) });
    git(clone, 'remote', 'set-url', 'origin', join(clone, 'no-such-remote'));
    const ci = run(clone, { GBRAIN_SURFACE_BASE_REF: 'origin/base', CI: 'true' });
    expect(ci.code).toBe(1);
    expect(ci.out).toContain('FAIL: check-public-surface: this change drops public entries, and the stable ref refs/tags/stable could not be fetched from origin, so it cannot tell which of them reached stable.');
    expect(ci.out).toMatch(/git: .*(does not appear to be a git repository|not found|No such file)/);
    expect(ci.out).not.toContain('mcp-tool `search`');
    const local = run(clone, { GBRAIN_SURFACE_BASE_REF: 'origin/base' });
    expect(local.code).toBe(1);
    expect(local.out).toContain('stable ref refs/tags/stable is unavailable');
    expect(local.out).toContain('mcp-tool `search` is removed or changed');
  });

  test('a fetch that hangs is stopped at its timeout and says so', () => {
    const stable = mergeClone({ [MANIFEST]: manifest({ 'mcp-tool': [] }) });
    hangOrigin(stable);
    const env = { GBRAIN_SURFACE_BASE_REF: 'origin/base', CI: 'true', GBRAIN_SURFACE_FETCH_TIMEOUT_S: '1' };
    const started = Date.now();
    const s = run(stable, env);
    expect(s.code).toBe(1);
    expect(s.out).toContain('could not be fetched from origin (timed out after 1 s)');
    const origin = repo({}, {});
    git(origin, 'checkout', '-q', 'base');
    write(origin, { [MANIFEST]: manifest({ 'mcp-tool': ['search', 'think'] }) });
    git(origin, 'commit', '-qam', 'base adds think');
    const deep = shallowClone(origin, 'head');
    hangOrigin(deep);
    const d = run(deep, env);
    expect(d.code).toBe(1);
    expect(d.out).toContain('no merge base between HEAD and origin/base, because the fetch that deepens the clone timed out after 1 s');
    expect(Date.now() - started).toBeLessThan(8000);
  }, 15000);

  test('a missing base ref fails under CI and skips locally', () => {
    const root = repo({}, {});
    const ci = run(root, { GBRAIN_SURFACE_BASE_REF: 'nope', CI: 'true' });
    expect(ci.code).toBe(1);
    expect(ci.out).toContain('base ref nope is not available');
    const local = run(root, { GBRAIN_SURFACE_BASE_REF: 'nope' });
    expect(local.code).toBe(0);
    expect(local.out).toContain('GBRAIN_CHECK_SKIPPED: base ref nope unavailable');
  });
});

describe('deprecation records', () => {
  test('a new record must give at least 14 days; an old record keeps its date', () => {
    const short = run(repo({}, { 'deprecations.d/search_limit_flag_1234.md': record('cli-flag', 'gbrain search --limit', '2026-11-29') }));
    expect(short.code).toBe(1);
    expect(short.out).toContain('remove_after 2026-11-29 is less than 14 days away');
    expect(run(repo({}, { 'deprecations.d/search_limit_flag_1234.md': record('cli-flag', 'gbrain search --limit', '2026-11-30') })).code).toBe(0);
    expect(run(repo({ 'deprecations.d/search_limit_flag_1234.md': record('cli-flag', 'gbrain search --limit', '2026-11-29') }, {})).code).toBe(0);
  });

  test('an announced date can move later, never earlier', () => {
    const path = 'deprecations.d/search_limit_flag_1234.md';
    const early = run(repo({ [path]: record('cli-flag', 'gbrain search --limit', '2026-12-20') },
      { [path]: record('cli-flag', 'gbrain search --limit', '2026-11-16'), [MANIFEST]: manifest({ 'cli-flag': ['gbrain search --match'] }) }));
    expect(early.code).toBe(1);
    expect(early.out).toContain(`${path}: remove_after moves from 2026-12-20 to 2026-11-16`);
    expect(run(repo({ [path]: record('cli-flag', 'gbrain search --limit', '2026-11-20') }, { [path]: record('cli-flag', 'gbrain search --limit', '2026-12-20') })).code).toBe(0);
  });

  test('a record on the base keeps the surface and name it was announced with', () => {
    const path = 'deprecations.d/search_limit_flag_1234.md';
    const r = run(repo({ [path]: record('cli-flag', 'gbrain search --limit', '2026-11-20') },
      { [path]: record('cli-flag', 'gbrain search --match', '2026-11-20'), [MANIFEST]: manifest({ 'cli-flag': ['gbrain search --limit'] }) }));
    expect(r.code).toBe(1);
    expect(r.out).toContain(`${path}: it named cli-flag \`gbrain search --limit\` on base; a record keeps the surface and name it was announced with, so add a new record for cli-flag \`gbrain search --match\``);
    expect(run(repo({ [path]: record('cli-flag', 'gbrain search --limit', '2026-11-20') }, { [path]: record('cli-flag', 'gbrain search --limit', '2026-11-20').replace('alice-example', 'bob-example') })).code).toBe(0);
  });

  test('a record with a bad surface, no owner or no date is refused', () => {
    const r = run(repo({}, { 'deprecations.d/bad_record_1234.md': '---\nsurface: cli-thing\nname: gbrain x\n---\nText.\n' }));
    expect(r.code).toBe(1);
    expect(r.out).toContain('surface: must be one of cli-command, cli-flag, mcp-tool, mcp-param, config-key, exit-code, page-format, json-field');
    expect(r.out).toContain('owner: is missing');
    expect(r.out).toContain('remove_after: must be a date (YYYY-MM-DD)');
  });

  test('a page-format or --json field record is accepted though the list does not hold those surfaces', () => {
    for (const surface of ['page-format', 'json-field']) {
      expect(run(repo({}, { 'deprecations.d/old_field_1234.md': record(surface, 'gbrain stats --json .old_field', '2026-11-30') })).code).toBe(0);
    }
  });
});

describe('new behaviour-change rows', () => {
  test('a new row needs kind:', () => {
    const r = run(repo({}, { 'behavior-changes.d/new_row_1234.md': 'Plain text.\n' }));
    expect(r.code).toBe(1);
    expect(r.out).toContain('behavior-changes.d/new_row_1234.md: a new behaviour-change row needs front matter with kind:');
    expect(run(repo({}, { 'behavior-changes.d/new_row_1234.md': '---\nkind: fix\n---\nPlain text.\n' })).code).toBe(0);
  });

  test('a row already on the base needs nothing', () => {
    expect(run(repo({ 'behavior-changes.d/old_row_1234.md': 'Plain text.\n' }, {})).code).toBe(0);
  });

  test('kind: breaking needs an exception or a matured deprecation', () => {
    const bare = run(repo({}, { 'behavior-changes.d/new_row_1234.md': '---\nkind: breaking\n---\nText.\n' }));
    expect(bare.code).toBe(1);
    expect(bare.out).toContain('kind: breaking needs exception: security or data-loss, or deprecation: <id>');
    expect(run(repo({}, { 'behavior-changes.d/new_row_1234.md': '---\nkind: breaking\nexception: security\n---\nText.\n' })).code).toBe(0);
    const young = run(repo({ 'deprecations.d/search_limit_flag_1234.md': record('cli-flag', 'gbrain search --limit', '2026-12-01') },
      { 'behavior-changes.d/new_row_1234.md': '---\nkind: breaking\ndeprecation: search_limit_flag_1234\n---\nText.\n' }));
    expect(young.code).toBe(1);
    expect(young.out).toContain('deprecation: search_limit_flag_1234 has not matured (remove_after 2026-12-01)');
    expect(run(repo({ 'deprecations.d/search_limit_flag_1234.md': record('cli-flag', 'gbrain search --limit', '2026-11-10') },
      { 'behavior-changes.d/new_row_1234.md': '---\nkind: breaking\ndeprecation: search_limit_flag_1234\n---\nText.\n' })).code).toBe(0);
  });
});

describe('golden changes', () => {
  const golden = 'test/fixtures/goldens/cli/search-help.txt';
  test('a CLI golden change with no row and no waiver is refused; either clears it', () => {
    const r = run(repo({ [golden]: 'old\n' }, { [golden]: 'new\n' }));
    expect(r.code).toBe(1);
    expect(r.out).toContain('CLI or agent-contract goldens changed (test/fixtures/goldens/cli/search-help.txt)');
    expect(run(repo({ [golden]: 'old\n' }, { [golden]: 'new\n', 'behavior-changes.d/new_row_1234.md': '---\nkind: add\n---\nText.\n' })).code).toBe(0);
    expect(run(repo({ [golden]: 'old\n' }, { [golden]: 'new\n', 'changelog.d/x.md': 'Entry.\n\n<!-- public-surface: no-behavior-change: help text reflowed -->\n' })).code).toBe(0);
  });

  test('a waiver already on the base does not cover a new golden change, whatever its file name', () => {
    const waiver = 'Entry.\n\n<!-- public-surface: no-behavior-change: help text reflowed -->\n';
    for (const name of ['changelog.d/x.md', 'changelog.d/café.md']) {
      const r = run(repo({ [golden]: 'old\n', [name]: waiver }, { [golden]: 'new\n' }));
      expect(r.code).toBe(1);
      expect(r.out).toContain('CLI or agent-contract goldens changed (test/fixtures/goldens/cli/search-help.txt)');
    }
  });

  test('other goldens are not covered', () => {
    expect(run(repo({ 'test/fixtures/goldens/doctor/a.json': '1\n' }, { 'test/fixtures/goldens/doctor/a.json': '2\n' })).code).toBe(0);
  });
});

describe('the committed manifest', () => {
  test('is fresh and lists documented surfaces by the names deprecations.d uses', async () => {
    expect(await buildMain(['--check'], join(import.meta.dir, '..', '..'))).toBe(0);
    expect(MANIFEST).toBe('docs/contracts/public-surface.json');
    const m = JSON.parse(await Bun.file(join(import.meta.dir, '..', '..', 'docs/contracts/public-surface.json')).text());
    expect(m['cli-command']).toContain('gbrain search');
    expect(m['cli-flag']).toContain('gbrain search --limit');
    expect(m['mcp-param']).toContain('search.query');
    expect(m['config-key']).toContain('engine');
    expect(typeof m['exit-code'].not_found).toBe('number');
  });

  test('lists only commands the CLI dispatches, and keeps MCP-only operations as tools', async () => {
    const { cliOps, OPERATION_MANIFEST } = await import('../../src/cli/op-manifest.ts');
    const { cliAliases } = await import('../../src/cli/flag-validation.ts');
    const { CLI_COMMANDS } = await import('../../src/cli/command-table.ts');
    const dispatched = (name: string) => cliOps.has(name) || cliAliases.has(name) || CLI_COMMANDS.some(r => r.name === name);
    const m = await buildSurface();
    expect(m['cli-command'].filter(c => !dispatched(c.slice('gbrain '.length)))).toEqual([]);
    expect(m['cli-flag'].filter(f => !dispatched(f.slice('gbrain '.length, f.indexOf(' --'))))).toEqual([]);
    const mcpOnly = OPERATION_MANIFEST.filter(op => !op.cliOnly && !op.cliHints?.name);
    expect(mcpOnly.length).toBeGreaterThan(0);
    for (const op of mcpOnly) {
      expect(m['mcp-tool']).toContain(op.name);
      for (const p of Object.keys(op.params)) expect(m['mcp-param']).toContain(`${op.name}.${p}`);
    }
  });
});