Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
10.0 KB
Raw Blame
#!/usr/bin/env bun
/**
 * One entry point for every generated artifact (GBRA-47 B8; DX-14).
 *
 *   bun run regen:all              regenerate every artifact, print what changed
 *   bun run regen:all --check      read-only: run every artifact's freshness check
 *                                  (what `bun run verify` runs as check:regen-all)
 *   bun run regen:all --goldens    also regenerate the offline contract goldens
 *                                  (deliberate: justify each changed golden in the PR body)
 *
 * Offline and keyless: generators run with provider keys and database URLs
 * removed from the environment. Idempotent: a second run changes nothing.
 * Goldens that need Postgres are never regenerated here; they are named with
 * their own command. Order matters: llms.txt inlines docs other generators
 * write, so it runs last.
 *
 * Exit: 0 fresh (or regenerated), 1 --check found stale artifacts or a
 * generator failed, 2 usage error.
 */
import { existsSync, readFileSync } from 'node:fs';
import { join, resolve } from 'node:path';

export interface Artifact { name: string; regen: string[]; check: string[] }

const HARNESS_DOCS_CHECK = `import { readFileSync } from 'node:fs';
import { renderHarnessReference } from './src/core/harness/registry.ts';
if (readFileSync('docs/guides/harness-adapters.md', 'utf8') !== renderHarnessReference()) {
  console.error('docs/guides/harness-adapters.md is stale');
  process.exit(1);
}`;

/**
 * Every `bun test` this script spawns. Bun does not apply bunfig.toml's
 * `[test] timeout`, so without the flag a cold PGLite init or a JIT-less
 * runner hits the 5 s default (#6187).
 */
const BUN_TEST = ['bun', 'test', '--timeout=60000'];

export const ARTIFACTS: Artifact[] = [
  { name: 'schema (src/schema-embedded)', regen: ['bun', 'run', 'scripts/build-schema.ts'], check: ['bash', 'scripts/check-schema-fresh.sh'] },
  { name: 'schema migrations bundle', regen: ['bun', 'run', 'scripts/build-schema-migrations.ts'], check: ['bash', 'scripts/check-schema-migrations-fresh.sh'] },
  { name: 'behavior-change table (behavior-changes.d)', regen: ['bun', 'scripts/build-behavior-changes.ts'], check: ['bun', 'scripts/build-behavior-changes.ts', '--check'] },
  { name: 'error-code registry docs', regen: ['bun', 'scripts/build-error-codes.ts'], check: ['bun', 'scripts/build-error-codes.ts', '--check'] },
  { name: 'agent operator protocol blocks', regen: ['bun', 'scripts/build-agent-protocol.ts'], check: ['bun', 'scripts/build-agent-protocol.ts', '--check'] },
  { name: 'lookup table copies', regen: ['bun', 'scripts/build-lookup-table.ts'], check: ['bun', 'scripts/build-lookup-table.ts', '--check'] },
  { name: 'harness adapter reference', regen: ['bun', 'run', 'scripts/build-harness-docs.ts'], check: ['bun', '-e', HARNESS_DOCS_CHECK] },
  { name: 'operation manifest', regen: ['bun', 'run', 'scripts/build-operation-manifest.ts'], check: [...BUN_TEST, 'test/operation-manifest.test.ts'] },
  { name: 'public surface (docs/contracts/public-surface.json)', regen: ['bun', 'scripts/build-public-surface.ts'], check: ['bun', 'scripts/build-public-surface.ts', '--check'] },
  { name: 'MCP tool catalog', regen: ['bun', 'run', 'scripts/generate-tool-catalog.ts'], check: ['bash', 'scripts/check-tool-catalog-fresh.sh'] },
  { name: 'skills manifest', regen: ['bun', 'run', 'scripts/generate-skills-manifest.ts'], check: ['bash', 'scripts/check-skills-manifest-fresh.sh'] },
  { name: 'bundled skills module', regen: ['bun', 'run', 'scripts/generate-bundled-skills.ts'], check: ['bun', 'run', 'scripts/generate-bundled-skills.ts', '--check'] },
  { name: 'eval metric glossary', regen: ['bun', 'run', 'scripts/generate-metric-glossary.ts'], check: ['bash', 'scripts/check-eval-glossary-fresh.sh'] },
  { name: 'CLI flag registry', regen: ['bun', 'run', 'scripts/generate-flag-registry.ts'], check: ['bun', 'run', 'scripts/generate-flag-registry.ts', '--check'] },
  { name: 'plugin tree + persona variants', regen: ['bun', 'run', 'scripts/generate-plugin-tree.ts', '--out', 'plugin', '--variants-out', 'plugin-variants'], check: ['bash', 'scripts/check-plugin-tree.sh'] },
  { name: 'structural suites manifest', regen: ['bun', 'scripts/classify-tests.ts'], check: ['bun', 'scripts/classify-tests.ts', '--check'] },
  { name: 'QM memory-provider contract', regen: ['bun', 'scripts/build-qm-memory-contract.ts'], check: ['bun', 'scripts/build-qm-memory-contract.ts', '--check'] },
  { name: 'llms.txt + llms-full.txt', regen: ['bun', 'run', 'scripts/build-llms.ts'], check: [...BUN_TEST, 'test/build-llms.test.ts'] },
];

/** Offline contract goldens: regenerated only with --goldens, each a reviewer-visible change to justify. */
export const CONTRACT_GOLDENS = [
  'test/export-surface-golden.test.ts',
  'test/cli-goldens.test.ts',
  'test/cli-dispatch-phase.test.ts',
  'test/engine-sql-sql-text.test.ts',
];

/** Goldens that need a Postgres database; never run here. */
export const POSTGRES_GOLDENS = [
  'GBRAIN_TEST_UPDATE_GOLDENS=1 DATABASE_URL=<test db> bun test --timeout=60000 test/e2e/schema-catalog-golden.test.ts',
  'GBRAIN_TEST_UPDATE_GOLDENS=1 DATABASE_URL=<test db> bun test --timeout=60000 test/e2e/doctor-json-golden.test.ts',
];

export const goldenArgv = (file: string): string[] => [...BUN_TEST, file];

const ROOT = resolve(import.meta.dir, '..');
const DOCS = 'docs/RELEASING.md#generated-artifacts';

export function offlineEnv(env: Record<string, string | undefined> = process.env): Record<string, string> {
  const out: Record<string, string> = {};
  for (const [k, v] of Object.entries(env)) {
    if (v === undefined || /_API_KEY$|_API_TOKEN$/.test(k) || k === 'DATABASE_URL' || k === 'GBRAIN_DATABASE_URL') continue;
    out[k] = v;
  }
  return out;
}

async function run(argv: string[], env: Record<string, string>): Promise<{ code: number; output: string }> {
  const child = Bun.spawn(argv, { cwd: ROOT, env, stdout: 'pipe', stderr: 'pipe' });
  const [out, err, code] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
  return { code, output: `${out}${err}` };
}

/** Dirty paths (git status) with a content hash, so a second change to an already-dirty file still shows. */
function dirtyState(): Map<string, string> {
  const r = Bun.spawnSync(['git', 'status', '--porcelain', '--untracked-files=all'], { cwd: ROOT, stdout: 'pipe' });
  return new Map(r.stdout.toString().split('\n').filter(Boolean).map(line => {
    const path = line.slice(3).replace(/^.* -> /, '');
    const file = join(ROOT, path);
    return [path, existsSync(file) ? String(Bun.hash(readFileSync(file))) : 'deleted'];
  }));
}

/** Run every freshness check (pool of 4); returns the stale artifacts with their output tails. */
export async function checkArtifacts(artifacts: Artifact[], env = offlineEnv()): Promise<Array<{ artifact: Artifact; tail: string }>> {
  const stale: Array<{ artifact: Artifact; tail: string }> = [];
  const queue = [...artifacts];
  await Promise.all(Array.from({ length: 4 }, async () => {
    for (let a = queue.shift(); a; a = queue.shift()) {
      const r = await run(a.check, env);
      if (r.code !== 0) stale.push({ artifact: a, tail: r.output.trim().split('\n').slice(-8).join('\n') });
    }
  }));
  return artifacts.flatMap(a => stale.filter(s => s.artifact === a));
}

export function staleReport(stale: Array<{ artifact: Artifact; tail: string }>): string {
  return [
    ...stale.flatMap(({ artifact, tail }) => [`STALE ${artifact.name} (check: ${artifact.check.slice(0, 3).join(' ')}${artifact.check.length > 3 ? ' …' : ''})`, ...tail.split('\n').map(l => `  | ${l}`)]),
    `regen:all --check: ${stale.length} generated artifact(s) stale: ${stale.map(s => s.artifact.name).join(', ')}`,
    'Why: a committed artifact no longer matches its generator, so CI fails the freshness gate.',
    'Fix: bun run regen:all   (then commit the changed files it lists)',
    `Docs: ${DOCS}`,
  ].join('\n');
}

if (import.meta.main) {
  const args = process.argv.slice(2);
  const unknown = args.filter(a => a !== '--check' && a !== '--goldens');
  if (unknown.length || (args.includes('--check') && args.includes('--goldens'))) {
    console.log('Usage: bun run regen:all [--check | --goldens]');
    process.exit(2);
  }
  const env = offlineEnv();
  if (args.includes('--check')) {
    const stale = await checkArtifacts(ARTIFACTS, env);
    if (stale.length) {
      console.log(staleReport(stale));
      process.exit(1);
    }
    console.log(`regen:all --check: all ${ARTIFACTS.length} generated artifacts fresh.`);
    process.exit(0);
  }

  const before = dirtyState();
  const steps = [...ARTIFACTS.map(a => ({ name: a.name, argv: a.regen, env })),
    ...(args.includes('--goldens') ? CONTRACT_GOLDENS.map(f => ({ name: `golden ${f}`, argv: goldenArgv(f), env: { ...env, GBRAIN_TEST_UPDATE_GOLDENS: '1' } })) : [])];
  const llms = steps.findIndex(s => s.name.startsWith('llms'));
  steps.push(...steps.splice(llms, 1));
  for (const step of steps) {
    const r = await run(step.argv, step.env);
    if (r.code !== 0) {
      console.log(r.output.trim().split('\n').slice(-20).join('\n'));
      console.log(`regen:all: FAILED at ${step.name} (${step.argv.join(' ')}, exit ${r.code}).`);
      console.log(`Fix: run that command directly, fix what it reports, then rerun bun run regen:all. Docs: ${DOCS}`);
      process.exit(1);
    }
    console.log(`regen:all: ${step.name} ok`);
  }
  const changed = [...dirtyState()].filter(([p, h]) => before.get(p) !== h).map(([p]) => p);
  console.log(changed.length
    ? `regen:all: ${changed.length} file(s) changed; commit them:\n${changed.map(p => `  ${p}`).join('\n')}`
    : 'regen:all: every generated artifact was already fresh; nothing changed.');
  if (args.includes('--goldens') && changed.some(p => p.includes('test/fixtures/goldens/'))) {
    console.log('Changed contract goldens are reviewer-visible behavior changes: justify each in the PR body.');
  }
  console.log(`Not regenerated here (need Postgres):\n${POSTGRES_GOLDENS.map(c => `  ${c}`).join('\n')}`);
  if (!args.includes('--goldens')) console.log(`Contract goldens (deliberate): bun run regen:all --goldens regenerates ${CONTRACT_GOLDENS.join(', ')}.`);
}