Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
#!/usr/bin/env bun
/**
* check:public-surface: stable's promise (docs/STABILITY.md "What stays the same on stable"), checked against the
* base branch on every pull request.
*
* bun scripts/check-public-surface.ts
*
* Against the merge base with the base ref ($GBRAIN_SURFACE_BASE_REF, default origin/master; a shallow clone is
* deepened until it has one) it refuses:
* 1. an entry of docs/contracts/public-surface.json that the base has and this tree drops (or an exit code whose
* number changed), unless deprecations.d/<id>.md names it (same surface and name, or the command or MCP tool a
* dropped flag or parameter belongs to) and its remove_after date has passed. Exempt: an entry the manifest at the
* stable release ($GBRAIN_SURFACE_STABLE_REF, default refs/tags/stable; fetched from origin when the clone lacks
* it, and under CI=true a fetch that fails or times out refuses) lacks, every drop when a new kind: breaking row
* has exception: security or data-loss, and, while no stable manifest can be read (it is said so), every drop
* when one has exception: revert;
* 2. a deprecations.d record added here whose remove_after is less than 14 days away, a record whose remove_after
* moved earlier or whose surface or name changed, or any record with a bad field;
* 3. a behavior-changes.d fragment added here with no `kind:`, or with `kind: breaking` and neither
* `exception: security|data-loss` nor `deprecation: <id>` naming a record whose remove_after has passed;
* 4. a change to the CLI or agent-contract goldens with no new behavior-changes.d fragment and no changelog.d line
* `<!-- public-surface: no-behavior-change: <reason> -->`.
* The manifest's freshness is regen:all's (scripts/build-public-surface.ts --check). Dates are UTC days;
* GBRAIN_SURFACE_TODAY (YYYY-MM-DD) overrides today for tests. When the base ref, a merge base or a file on the merge
* base is unavailable the check fails under CI=true and skips locally. Fetches (the stable ref, deepening a shallow
* clone with --filter=blob:none, since GitHub's pack-objects crashes on tree:0 for a shallow clone that is not partial) stop after
* 20 s and 30 s, or $GBRAIN_SURFACE_FETCH_TIMEOUT_S; a failed fetch prints git's own error. Exit: 0 ok or skipped,
* 1 refused.
*/
import { spawnSync } from 'node:child_process';
import { existsSync, readdirSync, readFileSync } from 'node:fs';
import { join } from 'node:path';
import { CHANGELOG_FRAGMENT_DIR, FRAGMENT_DIR, ID, parseNoticeFragment } from './build-behavior-changes.ts';
import { MANIFEST, SURFACES, type PublicSurface, type Surface } from './build-public-surface.ts';
export const DEPRECATION_DIR = 'deprecations.d';
export const GOLDEN_DIRS = ['test/fixtures/goldens/cli/', 'test/fixtures/agent-contract/'];
export const NO_BEHAVIOR_CHANGE = /<!--\s*public-surface:\s*no-behavior-change:\s*\S[^>]*-->/;
const NOTICE_DAYS = 14;
const SEE = 'See: docs/STABILITY.md#what-stays-the-same-on-stable and deprecations.d/README.md';
const DATE = /^\d{4}-\d{2}-\d{2}$/;
const RECORD_SURFACES: readonly string[] = [...SURFACES, 'page-format', 'json-field'];
export interface Deprecation { id: string; surface: string; name: string; owner: string; remove_after: string }
const frontOf = (raw: string) => {
const out: Record<string, string> = {};
const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(raw);
for (const line of (m?.[1] ?? '').split(/\r?\n/)) {
const kv = /^([a-z_]+)\s*:\s*(.*?)\s*$/.exec(line);
if (kv) out[kv[1]!] = kv[2]!.replace(/^(['"])(.*)\1$/, '$2');
}
return out;
};
const addDays = (day: string, n: number) => new Date(Date.parse(day + 'T00:00:00Z') + n * 86_400_000).toISOString().slice(0, 10);
/** Entries the base has and the head lacks, as surface + name (an exit code whose number changed counts). */
export function droppedEntries(base: PublicSurface, head: PublicSurface): Array<{ surface: string; name: string }> {
const out: Array<{ surface: string; name: string }> = [];
for (const surface of SURFACES) {
if (surface === 'exit-code') {
for (const [code, exit] of Object.entries(base['exit-code'] ?? {})) if (head['exit-code']?.[code] !== exit) out.push({ surface, name: code });
continue;
}
const kept = new Set(head[surface] ?? []);
for (const name of base[surface] ?? []) if (!kept.has(name)) out.push({ surface, name });
}
return out;
}
export function main(opts: { cwd?: string; env?: Record<string, string | undefined>; log?: (line: string) => void } = {}): number {
const root = opts.cwd ?? process.cwd();
const env = opts.env ?? process.env;
const log = opts.log ?? ((line: string) => console.log(line));
const today = env.GBRAIN_SURFACE_TODAY || new Date().toISOString().slice(0, 10);
const git = (...args: string[]) => {
const r = spawnSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
return { ok: r.status === 0, out: r.stdout ?? '', err: (r.stderr ?? '').trim() };
};
const fetchTimeout = (seconds: number) => Number(env.GBRAIN_SURFACE_FETCH_TIMEOUT_S) || seconds;
let fetchError = '';
const fetch = (seconds: number, ...args: string[]): 'ok' | 'timeout' | 'failed' => {
fetchError = '';
const r = spawnSync('git', ['fetch', '--no-tags', '--quiet', ...args], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'ignore', 'pipe'], timeout: fetchTimeout(seconds) * 1000, killSignal: 'SIGKILL' });
if (r.status === 0) return 'ok';
if ((r.error as NodeJS.ErrnoException | undefined)?.code === 'ETIMEDOUT') return 'timeout';
fetchError = (r.stderr ?? '').split('\n').map(l => l.trim()).filter(Boolean).slice(-4).join(' / ').slice(-600);
return 'failed';
};
const logFetchError = (result: string | null) => { if (result === 'failed' && fetchError) log(`git: ${fetchError}`); };
const ref = env.GBRAIN_SURFACE_BASE_REF || 'origin/master';
if (!git('rev-parse', '--verify', '-q', `${ref}^{commit}`).ok) {
if (env.CI === 'true') {
log(`FAIL: check-public-surface: base ref ${ref} is not available.`);
log('Fix: fetch it in the workflow (git fetch --no-tags --depth=1 origin +refs/heads/master:refs/remotes/origin/master)');
return 1;
}
log(`GBRAIN_CHECK_SKIPPED: base ref ${ref} unavailable`);
return 0;
}
let mergeBase = git('merge-base', ref, 'HEAD');
let deepened: ReturnType<typeof fetch> | null = null;
if (!mergeBase.ok && git('rev-parse', '--is-shallow-repository').out.trim() === 'true') {
const tip = git('rev-parse', `${ref}^{commit}`).out.trim();
const parents = git('cat-file', '-p', 'HEAD').out.split('\n').filter(l => l.startsWith('parent ')).map(l => l.slice('parent '.length));
if (parents.includes(tip)) mergeBase = { ok: true, out: tip, err: '' };
for (const depth of [200, 2000]) {
if (mergeBase.ok || deepened === 'timeout') break;
deepened = fetch(30, '--filter=blob:none', `--deepen=${depth}`, 'origin', git('rev-parse', 'HEAD').out.trim(), tip);
mergeBase = git('merge-base', ref, 'HEAD');
}
}
if (!mergeBase.ok) {
if (env.CI === 'true') {
log(`FAIL: check-public-surface: no merge base between HEAD and ${ref}, ${deepened === 'timeout' ? `because the fetch that deepens the clone timed out after ${fetchTimeout(30)} s` : 'even after deepening the clone'}.`);
logFetchError(deepened);
log('Fix: fetch more history in the workflow (actions/checkout fetch-depth: 0)');
return 1;
}
log(`GBRAIN_CHECK_SKIPPED: no merge base between HEAD and ${ref}`);
return 0;
}
const base = mergeBase.out.trim();
let unreadable: { path: string; error: string } | null = null;
const onBase = (path: string) => {
const listed = git('ls-tree', '-z', '--name-only', base, '--', path);
if (!listed.ok) unreadable ??= { path, error: listed.err };
return listed.ok && listed.out === `${path}\0`;
};
const readBase = (path: string) => {
if (!onBase(path)) return null;
const shown = git('show', `${base}:${path}`);
if (!shown.ok) unreadable ??= { path, error: shown.err };
return shown.ok ? shown.out : null;
};
const listDir = (dir: string) => (existsSync(join(root, dir)) ? readdirSync(join(root, dir)).filter(f => f.endsWith('.md') && f !== 'README.md').sort() : []);
const problems: string[] = [];
const records = new Map<string, Deprecation>();
for (const f of listDir(DEPRECATION_DIR)) {
const id = f.replace(/\.md$/, '');
const path = `${DEPRECATION_DIR}/${f}`;
const front = frontOf(readFileSync(join(root, path), 'utf8'));
const record = { id, surface: front.surface ?? '', name: front.name ?? '', owner: front.owner ?? '', remove_after: front.remove_after ?? '' };
const bad = [
!ID.test(id) && 'its file name is not an id (lowercase letters, digits and _, starting with a letter)',
!RECORD_SURFACES.includes(record.surface) && `surface: must be one of ${RECORD_SURFACES.join(', ')}`,
!record.name && 'name: is missing',
!record.owner && 'owner: is missing',
!DATE.test(record.remove_after) && 'remove_after: must be a date (YYYY-MM-DD)',
].filter(Boolean);
for (const b of bad) problems.push(`${path}: ${b}`);
const baseText = readBase(path);
const baseFront = baseText === null ? null : frontOf(baseText);
const baseDate = baseFront ? baseFront.remove_after ?? '' : null;
if (!bad.length && baseFront?.surface && baseFront.name && (baseFront.surface !== record.surface || baseFront.name !== record.name)) {
problems.push(`${path}: it named ${baseFront.surface} \`${baseFront.name}\` on ${ref}; a record keeps the surface and name it was announced with, so add a new record for ${record.surface} \`${record.name}\``);
}
if (!bad.length && baseDate !== null && DATE.test(baseDate) && record.remove_after < baseDate) {
problems.push(`${path}: remove_after moves from ${baseDate} to ${record.remove_after}; an announced date can move later, never earlier`);
}
if (!bad.length && baseDate === null && record.remove_after < addDays(today, NOTICE_DAYS)) {
problems.push(`${path}: remove_after ${record.remove_after} is less than ${NOTICE_DAYS} days away; a removal is announced at least ${NOTICE_DAYS} days ahead (${addDays(today, NOTICE_DAYS)} or later)`);
}
records.set(id, record);
}
const matured = (r: Deprecation | undefined) => !!r && DATE.test(r.remove_after) && r.remove_after <= today;
const newNotices = listDir(FRAGMENT_DIR).filter(f => !onBase(`${FRAGMENT_DIR}/${f}`))
.map(f => ({ path: `${FRAGMENT_DIR}/${f}`, ...parseNoticeFragment(readFileSync(join(root, FRAGMENT_DIR, f), 'utf8')) }));
const exceptions = new Set(newNotices.filter(n => n.front.kind === 'breaking' && n.front.exception).map(n => n.front.exception));
const unreadableBase = (): number | null => {
if (!unreadable) return null;
const { path, error } = unreadable;
if (env.CI === 'true') {
log(`FAIL: check-public-surface: ${path} could not be read at ${ref}'s merge base ${base.slice(0, 12)}, so the check cannot compare with it.`);
if (error) log(`git: ${error.split('\n').filter(Boolean).slice(-4).join(' / ').slice(-600)}`);
log('Fix: rerun once origin answers, or fetch full history in the workflow (actions/checkout fetch-depth: 0)');
return 1;
}
log(`GBRAIN_CHECK_SKIPPED: ${path} could not be read at the merge base ${base.slice(0, 12)}`);
return 0;
};
const baseManifest = readBase(MANIFEST);
const manifestUnread = unreadableBase();
if (manifestUnread !== null) return manifestUnread;
if (baseManifest !== null && existsSync(join(root, MANIFEST))) {
const head: PublicSurface = JSON.parse(readFileSync(join(root, MANIFEST), 'utf8'));
const dropped = exceptions.has('security') || exceptions.has('data-loss') ? [] : droppedEntries(JSON.parse(baseManifest), head);
const stableRef = env.GBRAIN_SURFACE_STABLE_REF || 'refs/tags/stable';
const resolveStable = () => git('rev-parse', '--verify', '-q', `${stableRef}^{commit}`);
let stableCommit = resolveStable();
if (dropped.length && !stableCommit.ok && stableRef.startsWith('refs/')) {
const shallow = git('rev-parse', '--is-shallow-repository').out.trim() === 'true';
const fetched = fetch(20, ...(shallow ? ['--depth=1'] : []), 'origin', `+${stableRef}:${stableRef}`);
stableCommit = resolveStable();
if (!stableCommit.ok && env.CI === 'true') {
log(`FAIL: check-public-surface: this change drops public entries, and the stable ref ${stableRef} could not be fetched from origin${fetched === 'timeout' ? ` (timed out after ${fetchTimeout(20)} s)` : ''}, so it cannot tell which of them reached stable.`);
logFetchError(fetched);
log(`Fix: rerun once origin answers, or fetch it in the workflow (git fetch --no-tags --depth=1 origin +${stableRef}:${stableRef})`);
return 1;
}
}
const stableManifest = stableCommit.ok ? git('show', `${stableCommit.out.trim()}:${MANIFEST}`) : null;
const stable: PublicSurface | null = stableManifest?.ok ? JSON.parse(stableManifest.out) : null;
if (!stableCommit.ok) log(`check-public-surface: stable ref ${stableRef} is unavailable (a shallow clone or a missing tag), so every entry counts as on stable`);
else if (!stable) log(`check-public-surface: stable (${stableRef}) has no ${MANIFEST} yet, so every entry counts as on stable`);
const onStable = (surface: string, name: string) => !stable
|| (surface === 'exit-code' ? name in (stable['exit-code'] ?? {}) && stable['exit-code'][name] !== head['exit-code']?.[name] : (stable[surface as Exclude<Surface, 'exit-code'>] ?? []).includes(name));
for (const { surface, name } of dropped) {
if (!onStable(surface, name) || (exceptions.has('revert') && !stable)) continue;
const parent = surface === 'cli-flag' ? { surface: 'cli-command', name: name.slice(0, name.lastIndexOf(' --')) }
: surface === 'mcp-param' ? { surface: 'mcp-tool', name: name.slice(0, name.indexOf('.')) } : null;
const record = [...records.values()].find(r => r.surface === surface && r.name === name)
?? [...records.values()].find(r => parent && r.surface === parent.surface && r.name === parent.name);
if (!record) problems.push(`${surface} \`${name}\` is removed or changed with no ${DEPRECATION_DIR}/<id>.md naming it (surface: ${surface}, name: ${name})${exceptions.has('revert') ? '; it is on stable, so exception: revert does not cover it' : ''}`);
else if (!matured(record)) problems.push(`${surface} \`${name}\` is removed before its record ${DEPRECATION_DIR}/${record.id}.md allows it (remove_after ${record.remove_after}); keep it working with a warning until then`);
}
} else if (baseManifest === null) {
log(`check-public-surface: ${ref} has no ${MANIFEST} yet; the removal check starts once it does`);
}
for (const { path, front, problems: invalid } of newNotices) {
for (const p of invalid) problems.push(`${path}: ${p}`);
if (!front.kind) { problems.push(`${path}: a new behaviour-change row needs front matter with kind: breaking, action, default, fix or add (${FRAGMENT_DIR}/README.md)`); continue; }
if (front.kind !== 'breaking' || front.exception) continue;
const record = front.deprecation ? records.get(front.deprecation) : undefined;
if (!front.deprecation) problems.push(`${path}: kind: breaking needs exception: security or data-loss, or deprecation: <id> naming a ${DEPRECATION_DIR} record whose remove_after has passed`);
else if (!record) problems.push(`${path}: deprecation: ${front.deprecation} names no ${DEPRECATION_DIR}/${front.deprecation}.md`);
else if (!matured(record)) problems.push(`${path}: deprecation: ${front.deprecation} has not matured (remove_after ${record.remove_after})`);
}
const goldenDiff = git('diff', '--name-only', base, '--', ...GOLDEN_DIRS);
if (!goldenDiff.ok) unreadable ??= { path: GOLDEN_DIRS.join(', '), error: goldenDiff.err };
const goldens = goldenDiff.out.split('\n').filter(Boolean);
if (goldens.length && !newNotices.length) {
const waived = listDir(CHANGELOG_FRAGMENT_DIR).some(f => !onBase(`${CHANGELOG_FRAGMENT_DIR}/${f}`) && NO_BEHAVIOR_CHANGE.test(readFileSync(join(root, CHANGELOG_FRAGMENT_DIR, f), 'utf8')));
if (!waived) problems.push(`CLI or agent-contract goldens changed (${goldens.slice(0, 3).join(', ')}${goldens.length > 3 ? `, +${goldens.length - 3} more` : ''}) with no new ${FRAGMENT_DIR} row; add one with its kind, or put <!-- public-surface: no-behavior-change: <reason> --> in your ${CHANGELOG_FRAGMENT_DIR} fragment`);
}
const goldensUnread = unreadableBase();
if (goldensUnread !== null) return goldensUnread;
if (!problems.length) {
log(`check-public-surface: ok against ${ref} (${records.size} deprecation record(s), ${newNotices.length} new behaviour-change row(s))`);
return 0;
}
for (const p of problems) log(`FAIL: ${p}`);
log('Why: stable promises that documented commands, flags, tools, config keys and exit codes change only after a 14-day announced deprecation, except for security and data-loss fixes; what never reached stable can go at once.');
log(SEE);
return 1;
}
if (import.meta.main) process.exit(main());