Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
15.9 KB
Raw Blame
/**
 * `gbrain migrate` engine graduation CLI (plan §7, DX amendments): routing,
 * flag parsing, the exit-3 consent payload, `--plan`, the run, run-scoped
 * verbs, the exit-code map (0/1/2/3/11/75/130) and secret hygiene, over a
 * fake orchestrator (the G2a module is exercised by its own lane's tests).
 * Serial: it points GBRAIN_HOME at a temp dir and reads the file-plane
 * opt-out from it.
 */
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { withEnv } from './helpers/with-env.ts';
import { opError } from '../src/core/ops/contract.ts';
import { renderCliError } from '../src/core/agent-output.ts';
import type { ProgressReporter } from '../src/core/progress.ts';
import type {
  GraduationCommandOptions, GraduationPlan, GraduationReceipt, GraduationStatusDoc,
} from '../src/core/persistence/engine-graduation.types.ts';
import { drainTimeoutError, inProgressError } from '../src/core/persistence/graduation-errors.ts';
import {
  parseGraduationArgs, routesToGraduation, runMigrateGraduation, type GraduationApi,
} from '../src/commands/migrate-graduation.ts';

const SECRET_URL = 'postgresql://alice:[email protected]:5432/brain';
let home: string;

beforeAll(() => {
  home = mkdtempSync(join(tmpdir(), 'gbrain-grad-cli-'));
  mkdirSync(join(home, '.gbrain'));
  writeFileSync(join(home, '.gbrain', 'config.json'), JSON.stringify({ engine: 'pglite', database_path: join(home, 'brain.pglite') }));
});
afterAll(() => { rmSync(home, { recursive: true, force: true }); });

const plan: GraduationPlan = {
  planHash: 'ph_0123456789abcdef01234567',
  source: { dataDir: '/home/alice-example/.gbrain/brain.pglite', brainId: 'brain-1', hostId: 'host-1' },
  target: { id: 'tid', host: 'db.acme-example.test', port: 5432, database: 'brain', user: 'alice' },
  routes: { main: 'postgresql://alice:***@db.acme-example.test:5432/brain', ddl: 'postgresql://alice:***@db.acme-example.test:5432/brain', urlEnv: 'GBRAIN_TARGET_URL' },
  triggerBypass: 'session_replication_role',
  tables: [{ relation: 'pages', class: 'carry', rows: 10, bytes: 100 }, { relation: 'query_cache', class: 'rebuild', rows: 3, bytes: 1 }],
  blockers: [],
  estimateSeconds: { copy: 1, verify: 1, doctor: 2, total: 4 },
  sourceMeasured: 'now',
  nextArgv: [],
};
const receipt: GraduationReceipt = {
  runId: 'run-1', state: 'authoritative', tables: [{ relation: 'pages', rows: 10, rootSha256: 'x', batches: [] }],
  triggerBypass: 'session_replication_role', replay: { status: 'passed', requestId: 'r1' }, timings: { copy: 1000 },
  targetDisplayUrl: 'postgresql://alice:***@db.acme-example.test:5432/brain', retainedPath: '/home/alice-example/.gbrain/brain.pglite.graduated-run-1',
  serveHandoff: true, doctor: { source: [], target: [] },
};
const statusDoc: GraduationStatusDoc = {
  schema_version: 1, state: 'copying', runId: 'run-1', to: 'postgres', source: plan.source, sourcePath: null,
  target: { identity: plan.target, displayUrl: plan.routes.main, row: 'copying', reachable: true }, receipt: null,
  liveRun: { pid: 123 }, tables: [], nextArgv: ['gbrain', 'migrate', '--status', '--json'],
};

function fakeApi(over: Partial<GraduationApi> = {}): GraduationApi & { calls: { fn: string; opts?: GraduationCommandOptions }[] } {
  const calls: { fn: string; opts?: GraduationCommandOptions }[] = [];
  return {
    calls,
    planGraduation: async (opts) => { calls.push({ fn: 'plan', opts }); return plan; },
    runGraduation: async (opts) => { calls.push({ fn: 'run', opts }); return receipt; },
    graduationStatus: async () => { calls.push({ fn: 'status' }); return statusDoc; },
    resumeGraduation: async (opts) => { calls.push({ fn: 'resume', opts }); return receipt; },
    rollbackGraduation: async (opts) => { calls.push({ fn: 'rollback', opts }); return { state: 'abandoned', restoredPath: null, dropped: [] }; },
    ...over,
  };
}

const silentProgress: ProgressReporter = { start() {}, tick() {}, heartbeat() {}, finish() {}, child() { return silentProgress; } };

async function run(args: string[], api = fakeApi(), extra: { env?: NodeJS.ProcessEnv; signal?: AbortSignal; stdin?: string } = {}) {
  const out: string[] = [];
  const err: string[] = [];
  const realStdout = process.stdout.write.bind(process.stdout);
  const realStderr = process.stderr.write.bind(process.stderr);
  process.stdout.write = ((s: string) => { out.push(String(s)); return true; }) as typeof process.stdout.write;
  process.stderr.write = ((s: string) => { err.push(String(s)); return true; }) as typeof process.stderr.write;
  try {
    const code = await withEnv({ GBRAIN_HOME: home }, () => runMigrateGraduation(args, {
      api, env: extra.env ?? { GBRAIN_TARGET_URL: SECRET_URL }, out: t => { out.push(t); }, err: t => { err.push(t); },
      progress: silentProgress, signal: extra.signal ?? new AbortController().signal,
      writeError: (e, o) => {
        const r = renderCliError(e, { json: o.json, command: 'migrate', tty: false });
        if (r.stdout) out.push(JSON.stringify({ ...(o.legacy ?? {}), ...JSON.parse(r.stdout) }));
        if (r.stderr) err.push(r.stderr);
        return r.exitCode;
      },
      ...(extra.stdin !== undefined ? { readStdin: async () => extra.stdin! } : {}),
    }));
    return { code, stdout: out.join(''), stderr: err.join(''), api };
  } finally {
    process.stdout.write = realStdout;
    process.stderr.write = realStderr;
  }
}

describe('routing', () => {
  const pglite = { engine: 'pglite' as const, database_path: '/x/brain.pglite' };
  test('PGLite --to postgres|supabase routes to graduation; other forms fall through', () => {
    expect(routesToGraduation(['--to', 'postgres', '--url-env', 'X'], pglite, 'linux')).toBe(true);
    expect(routesToGraduation(['--to', 'supabase'], pglite, 'darwin')).toBe(true);
    expect(routesToGraduation(['--to=postgres'], pglite, 'linux')).toBe(true);
    expect(routesToGraduation(['--to', 'pglite'], { engine: 'postgres', database_url: 'postgresql://h/db' }, 'linux')).toBe(false);
    expect(routesToGraduation(['embeddings', '--to', 'openai:x'], pglite, 'linux')).toBe(false);
    expect(routesToGraduation(['--to', 'postgres', '--help'], pglite, 'linux')).toBe(false);
    expect(routesToGraduation(['--to', 'postgres'], { engine: 'postgres', database_url: 'postgresql://h/db' }, 'linux')).toBe(false);
  });
  test('opt-out and Windows keep the legacy copier for the bare run; run-scoped verbs always route', () => {
    expect(routesToGraduation(['--to', 'postgres'], { ...pglite, migrate: { graduation: false } }, 'linux')).toBe(false);
    expect(routesToGraduation(['--to', 'postgres'], pglite, 'win32')).toBe(false);
    for (const verb of ['--status', '--resume', '--rollback-to-source', '--plan', '--dry-run']) {
      expect(routesToGraduation([verb], { ...pglite, migrate: { graduation: false } }, 'win32')).toBe(true);
    }
  });
});

describe('parseGraduationArgs', () => {
  test('modes, aliases and escape hatches', () => {
    expect(parseGraduationArgs(['--to', 'supabase', '--dry-run']).mode).toBe('plan');
    expect(parseGraduationArgs(['--status']).mode).toBe('status');
    const a = parseGraduationArgs(['--to', 'postgres', '--url-env', 'U', '--drain-timeout', '120', '--trigger-bypass', 'disable-trigger', '--batch-size', '500', '--yes', '--expect', 'ph_x']);
    expect(a).toMatchObject({ mode: 'run', to: 'postgres', urlEnv: 'U', drainTimeoutSec: 120, triggerBypass: 'disable_trigger', batchSize: 500, yes: true, expect: 'ph_x' });
    expect(parseGraduationArgs(['--to', 'postgres']).drainTimeoutSec).toBe(60);
    expect(parseGraduationArgs(['--to', 'postgres', '--url', '-']).urlFromStdin).toBe(true);
  });
  test.each([
    [['--plan', '--status']], [['--resume', '--rollback-to-source']], [['--to', 'mysql']], [['--to', 'pglite', '--plan']],
    [['--plan']], [['--to', 'postgres', '--url', 'u', '--url-env', 'V']], [['--to', 'postgres', '--drain-timeout', '0']],
    [['--to', 'postgres', '--trigger-bypass', 'off']], [['--status', '--yes']], [['--to', 'postgres', '--url']],
  ])('usage error %j', (args) => {
    let code: string | undefined;
    try { parseGraduationArgs(args); } catch (e) { code = (e as { code?: string }).code; }
    expect(code).toBe('invalid_params');
  });
});

describe('runMigrateGraduation', () => {
  test('bare run: exit 3 consent payload bound to the plan, never the password', async () => {
    const r = await run(['--to', 'supabase', '--url-env', 'GBRAIN_TARGET_URL', '--json']);
    expect(r.code).toBe(3);
    const doc = JSON.parse(r.stdout);
    expect(doc.code).toBe('confirmation_required');
    expect(doc.effects).toEqual(['egress', 'destructive']);
    expect(doc.plan_hash).toBe(plan.planHash);
    expect(doc.fix.argv).toEqual(['gbrain', 'migrate', '--to', 'supabase', '--url-env', 'GBRAIN_TARGET_URL', '--yes', '--expect', plan.planHash]);
    expect(doc.fix.next).toBe('ask_user');
    expect(doc.preview.argv).toEqual(['gbrain', 'migrate', '--to', 'supabase', '--url-env', 'GBRAIN_TARGET_URL', '--plan', '--json']);
    expect(doc.user_message).toContain('db.acme-example.test');
    expect(doc.what_moves.length).toBeGreaterThan(0);
    expect(doc.what_stays.join(' ')).toContain('graduated');
    expect(r.api.calls.map(c => c.fn)).toEqual(['plan']);
    expect(r.api.calls[0]!.opts).toMatchObject({ to: 'supabase', urlEnv: 'GBRAIN_TARGET_URL', drainTimeoutMs: 60_000, yes: false });
    expect(r.stdout + r.stderr).not.toContain('s3cret-pw');
  });

  test('--yes without --expect re-plans and refuses with the fresh hash; --expect alone on a changed plan is preview_changed', async () => {
    const yes = await run(['--to', 'postgres', '--url-env', 'GBRAIN_TARGET_URL', '--yes', '--json']);
    expect(yes.code).toBe(3);
    expect(JSON.parse(yes.stdout).fix.argv).toContain(plan.planHash);
    const stale = await run(['--to', 'postgres', '--url-env', 'GBRAIN_TARGET_URL', '--expect', 'ph_stale', '--json']);
    expect(stale.code).toBe(1);
    expect(JSON.parse(stale.stdout).code).toBe('preview_changed');
  });

  test('--force and escape hatches are echoed into the approved command', async () => {
    const r = await run(['--to', 'postgres', '--url-env', 'GBRAIN_TARGET_URL', '--force', '--batch-size', '200', '--json']);
    expect(r.code).toBe(3);
    expect(JSON.parse(r.stdout).fix.argv).toEqual(['gbrain', 'migrate', '--to', 'postgres', '--url-env', 'GBRAIN_TARGET_URL', '--batch-size', '200', '--force', '--yes', '--expect', plan.planHash]);
  });

  test('--plan: exit 0, one document with the plan and the next command', async () => {
    const r = await run(['--to', 'postgres', '--url-env', 'GBRAIN_TARGET_URL', '--plan', '--json']);
    expect(r.code).toBe(0);
    const doc = JSON.parse(r.stdout);
    expect(doc).toMatchObject({ schema_version: 1, status: 'plan', plan: { planHash: plan.planHash } });
    expect(doc.next.command).toBe(`gbrain migrate --to postgres --url-env GBRAIN_TARGET_URL --yes --expect ${plan.planHash}`);
  });

  test('the approved run: receipt, retained copy, doctor, mcp expose, credentials and MCP restart notes', async () => {
    const r = await run(['--to', 'postgres', '--url-env', 'GBRAIN_TARGET_URL', '--yes', '--expect', plan.planHash, '--json']);
    expect(r.code).toBe(0);
    const doc = JSON.parse(r.stdout);
    expect(doc.status).toBe('graduated');
    expect(doc.next_steps[0].argv).toEqual(['gbrain', 'mcp', 'expose']);
    expect(doc.credentials).toContain('stay valid');
    expect(doc.mcp_client_restart).toContain('restart your MCP client');
    expect(r.api.calls.map(c => c.fn)).toEqual(['run']);
    expect(r.api.calls[0]!.opts).toMatchObject({ expectPlanHash: plan.planHash, yes: true });
    const human = await run(['--to', 'postgres', '--url-env', 'GBRAIN_TARGET_URL', '--yes', '--expect', plan.planHash]);
    expect(human.stdout).toContain('Target doctor: no failing checks');
    expect(human.stdout).toContain('gbrain mcp expose');
  });

  test('--url - reads the URL from stdin and passes it only to the orchestrator', async () => {
    const r = await run(['--to', 'postgres', '--url', '-', '--plan', '--json'], fakeApi(), { stdin: `${SECRET_URL}\n` });
    expect(r.code).toBe(0);
    expect(r.api.calls[0]!.opts!.url).toBe(SECRET_URL);
    expect(r.stdout + r.stderr).not.toContain('s3cret-pw');
  });

  test('--url-env naming an unset variable is a usage error (exit 2)', async () => {
    const r = await run(['--to', 'postgres', '--url-env', 'NOPE_URL', '--plan', '--json'], fakeApi(), { env: {} });
    expect(r.code).toBe(2);
    expect(JSON.parse(r.stdout).code).toBe('invalid_params');
  });

  test('run-scoped verbs need no target flags', async () => {
    const status = await run(['--status', '--json']);
    expect(status.code).toBe(0);
    expect(JSON.parse(status.stdout)).toMatchObject({ state: 'copying', runId: 'run-1' });
    expect((await run(['--resume', '--json'])).api.calls.map(c => c.fn)).toEqual(['resume']);
    const rb = await run(['--rollback-to-source', '--json']);
    expect(JSON.parse(rb.stdout)).toMatchObject({ status: 'abandoned' });
  });

  test('exit-code map: drain timeout 11 (blocked 1), in progress 75, SIGINT 130, refusal 1', async () => {
    const drain = await run(['--resume', '--json'], fakeApi({ resumeGraduation: async () => { throw drainTimeoutError({ timeoutSec: 60, blockers: [{ kind: 'request', id: 'r', detail: 'running', needsUser: false }] }); } }));
    expect(drain.code).toBe(11);
    expect(JSON.parse(drain.stdout).resume_command).toEqual(['gbrain', 'migrate', '--resume', '--drain-timeout', '120']);
    const blocked = await run(['--resume', '--json'], fakeApi({ resumeGraduation: async () => { throw drainTimeoutError({ timeoutSec: 60, blockers: [{ kind: 'writer_admin_lock', id: 'l', detail: 'locked', argv: ['gbrain', 'sources', 'writer', 'unlock'], needsUser: true }] }); } }));
    expect(blocked.code).toBe(1);
    const orchestratorBlocked = await run(['--resume', '--json'], fakeApi({ resumeGraduation: async () => { throw drainTimeoutError({ blockers: [{ kind: 'dangling_reference', id: 'oauth_clients.c1', detail: 'bound to a missing source', argv: ['gbrain', 'auth', 'revoke-client', 'c1'], needsUser: true }], timeoutSec: 60 }); } }));
    expect(orchestratorBlocked.code).toBe(1);
    const orchestratorProgressing = await run(['--resume', '--json'], fakeApi({ resumeGraduation: async () => { throw drainTimeoutError({ blockers: [{ kind: 'request', id: 'r', detail: 'running', needsUser: false }], timeoutSec: 60 }); } }));
    expect(orchestratorProgressing.code).toBe(11);
    const busy = await run(['--resume', '--json'], fakeApi({ resumeGraduation: async () => { throw inProgressError({ pid: 9 }); } }));
    expect(busy.code).toBe(75);
    const ctrl = new AbortController();
    const sigint = await run(['--resume', '--json'], fakeApi({ resumeGraduation: async () => { ctrl.abort(); throw new Error('stopped at batch boundary'); } }), { signal: ctrl.signal });
    expect(sigint.code).toBe(130);
    expect(JSON.parse(sigint.stdout)).toMatchObject({ code: 'interrupted', resume_command: ['gbrain', 'migrate', '--resume'] });
    const refused = await run(['--resume', '--json'], fakeApi({ resumeGraduation: async () => { throw opError('graduation_target_not_empty', 'not empty', 'pick another'); } }));
    expect(refused.code).toBe(1);
  });

  test('migrate.graduation=false refuses the plan instead of silently running the legacy copier', async () => {
    const optedOut = mkdtempSync(join(tmpdir(), 'gbrain-grad-optout-'));
    mkdirSync(join(optedOut, '.gbrain'));
    writeFileSync(join(optedOut, '.gbrain', 'config.json'), JSON.stringify({ engine: 'pglite', migrate: { graduation: false } }));
    try {
      const code = await withEnv({ GBRAIN_HOME: optedOut }, () => runMigrateGraduation(['--to', 'postgres', '--plan', '--json'],
        { api: fakeApi(), env: {}, out: () => {}, err: () => {}, progress: silentProgress, signal: new AbortController().signal }));
      expect(code).toBe(2);
    } finally {
      rmSync(optedOut, { recursive: true, force: true });
    }
  });
});