Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
20.2 KB
Raw Blame
/**
 * doctor/checks/backup-coverage.ts — checkBackupCoverage.
 *
 * Pins the D4 trust boundary: git probes against DB-supplied local_path run
 * ONLY on the trusted local doctor path (localOnly: true). The remote surface
 * is a cache-only, AGGREGATE-ONLY reader — it must never spawn git, never
 * touch the engine, and never surface asset ids / local paths (counts only).
 *
 * Isolation: tmp GBRAIN_HOME (configDir() appends '.gbrain'), the status-file
 * path seams, real tmp git fixtures (no-origin repo; origin-backed clean repo
 * pushed to a local bare — file transport, no network), and a minimal engine
 * stub cast to BrainEngine that serves `sources` / `pages` via executeRaw.
 */
import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { execFileSync } from 'node:child_process';
import { join } from 'node:path';
import { tmpdir } from 'node:os';

import { checkBackupCoverage } from '../src/commands/doctor/checks/backup-coverage.ts';
import {
  BACKUP_STATUS_SCHEMA_VERSION,
  __setBackupIntervalForTests,
  __setBackupNagStatePathForTests,
  __setBackupStatusPathForTests,
  saveBackupStatus,
  type BackupStatus,
} from '../src/core/backup/status-file.ts';
import type { BrainEngine } from '../src/core/engine.ts';

const ENV_KEYS = ['GBRAIN_HOME', 'GBRAIN_BACKUP_CHECK', 'GBRAIN_BACKUP_CHECK_DAYS'] as const;

let tmp: string;
let saved: Record<string, string | undefined>;
let statusFile: string;

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), 'gb-bkcov-'));
  saved = {};
  for (const k of ENV_KEYS) {
    saved[k] = process.env[k];
    delete process.env[k];
  }
  process.env.GBRAIN_HOME = tmp; // configDir() === join(tmp, '.gbrain')
  statusFile = join(tmp, 'state', 'backup-status.json');
  __setBackupStatusPathForTests(statusFile);
  __setBackupNagStatePathForTests(join(tmp, 'state', 'backup-nag-state.json'));
});

afterEach(() => {
  __setBackupStatusPathForTests(null);
  __setBackupNagStatePathForTests(null);
  __setBackupIntervalForTests(null);
  for (const k of ENV_KEYS) {
    if (saved[k] === undefined) delete process.env[k];
    else process.env[k] = saved[k];
  }
  rmSync(tmp, { recursive: true, force: true });
});

// ── Fixtures ─────────────────────────────────────────────────────────────────

function git(dir: string, args: string[]): void {
  execFileSync(
    'git',
    ['-C', dir, '-c', '[email protected]', '-c', 'user.name=t', '-c', 'commit.gpgsign=false', ...args],
    { stdio: ['ignore', 'ignore', 'ignore'], timeout: 30_000 },
  );
}

/** Local git repo with one commit and NO origin remote. */
function makeNoOriginRepo(name: string): string {
  const dir = join(tmp, name);
  mkdirSync(dir, { recursive: true });
  execFileSync('git', ['init', '-q', '-b', 'main', dir], { stdio: ['ignore', 'ignore', 'ignore'] });
  writeFileSync(join(dir, 'note.md'), '# hello\n');
  git(dir, ['add', '.']);
  git(dir, ['commit', '-q', '-m', 'init']);
  return dir;
}

/** Clean repo pushed to a local bare origin (file transport — no network). */
function makeHealthyRepo(name: string): string {
  const dir = makeNoOriginRepo(name);
  const bare = join(tmp, `${name}-origin.git`);
  execFileSync('git', ['init', '-q', '--bare', '-b', 'main', bare], { stdio: ['ignore', 'ignore', 'ignore'] });
  git(dir, ['remote', 'add', 'origin', bare]);
  git(dir, ['push', '-q', '-u', 'origin', 'main']);
  return dir;
}

/** Minimal engine stub (dispatch-response-meta idiom) — never a real PGLite. */
function makeEngine(sourcePaths: Array<{ id: string; local_path: string }>, pageCount = 0): BrainEngine {
  return {
    kind: 'pglite',
    executeRaw: async (sql: string) => {
      if (/FROM sources/i.test(sql)) {
        return sourcePaths.map((s) => ({
          id: s.id,
          name: s.id,
          local_path: s.local_path,
          last_commit: null,
          last_sync_at: null,
          config: '{}',
          created_at: new Date(),
          archived: false,
          newest_content_at: null,
        }));
      }
      if (/FROM pages/i.test(sql)) return [{ n: pageCount }];
      throw new Error(`unexpected sql in stub: ${sql}`);
    },
  } as unknown as BrainEngine;
}

/** Engine stub that throws on ANY property access — the remote-path trust pin. */
function makeThrowingEngine(): BrainEngine {
  return new Proxy(
    {},
    {
      get(_t, prop) {
        throw new Error(`engine touched on remote/disabled path: ${String(prop)}`);
      },
    },
  ) as unknown as BrainEngine;
}

function makeWarnCache(assetId: string): BackupStatus {
  return {
    schema_version: BACKUP_STATUS_SCHEMA_VERSION,
    checked_at: new Date(Date.now() - 60_000).toISOString(),
    gbrain_version: '0.0.0-test',
    interval_days: 30,
    computed_by: 'cli',
    overall: 'warn',
    totals: { assets: 1, no_remote: 1, unpushed: 0, failing: 0, recoverable_repos: 0, pages_at_risk: 0 },
    assets: [{ kind: 'source_repo', id: assetId, state: 'no_remote', detail: 'fixture', fix_argv: null }],
  };
}

// ── Local (trusted) path: probes run ─────────────────────────────────────────

describe('checkBackupCoverage — localOnly (trusted, probes run)', () => {
  test('no-origin source repo → warn naming the asset, points at gbrain backup status', async () => {
    const repo = makeNoOriginRepo('src-a');
    const check = await checkBackupCoverage(makeEngine([{ id: 'src-a', local_path: repo }]), {
      localOnly: true,
    });

    expect(check.name).toBe('backup_coverage');
    expect(check.status).toBe('warn');
    expect(check.message).toContain('gbrain backup status');
    expect(check.message).toContain('src-a');
    expect(check.message).toContain('no git remote');

    const details = check.details as { totals: BackupStatus['totals']; computed_by: string };
    expect(details.totals.no_remote).toBe(1);
    expect(details.computed_by).toBe('doctor');
    // Probed compute persists the verdict cache (getBackupStatus discipline).
    expect(existsSync(statusFile)).toBe(true);
  });

  test('healthy repo (origin, pushed, clean) → ok with recoverable count', async () => {
    const repo = makeHealthyRepo('src-b');
    const check = await checkBackupCoverage(makeEngine([{ id: 'src-b', local_path: repo }], 3), {
      localOnly: true,
    });

    expect(check.name).toBe('backup_coverage');
    expect(check.status).toBe('ok');
    expect(check.message).toContain('1 knowledge repo(s) have verified remote commits');
    expect(check.message).toContain('last checked');

    const details = check.details as { totals: BackupStatus['totals'] };
    expect(details.totals.recoverable_repos).toBe(1);
    expect(details.totals.no_remote).toBe(0);
  });

  test('warn with zero no_remote assets names the assets and reasons that caused it', async () => {
    const dirty = makeHealthyRepo('src-dirty');
    writeFileSync(join(dirty, 'note.md'), '# edited, not committed\n');
    const plain = join(tmp, 'src-plain');
    mkdirSync(plain, { recursive: true });

    const check = await checkBackupCoverage(
      makeEngine([
        { id: 'src-dirty', local_path: dirty },
        { id: 'src-plain', local_path: plain },
      ]),
      { localOnly: true },
    );

    expect(check.status).toBe('warn');
    expect(check.message).toContain('src-dirty (dirty)');
    expect(check.message).toContain('src-plain (not_a_git_repo)');
    expect(check.message).not.toContain('no git remote');
    expect(check.message).toContain('gbrain backup status');
  });

  test('more than five blocking assets → the first five are named, the rest counted', async () => {
    const sources = Array.from({ length: 6 }, (_, i) => {
      const dir = join(tmp, `plain-${i}`);
      mkdirSync(dir, { recursive: true });
      return { id: `plain-${i}`, local_path: dir };
    });

    const check = await checkBackupCoverage(makeEngine(sources), { localOnly: true });

    expect(check.message).toContain('6 knowledge asset(s) lack verified recovery:');
    expect(check.message).toContain('plain-4 (not_a_git_repo), and 1 more.');
    expect(check.message).not.toContain('plain-5');
  });

  test('degraded compute with no assets leads with the unreadable database', async () => {
    const engine = {
      kind: 'pglite',
      executeRaw: async (sql: string) => {
        if (/FROM sources/i.test(sql)) return [];
        throw new Error('pages unreadable');
      },
    } as unknown as BrainEngine;

    const check = await checkBackupCoverage(engine, { localOnly: true });

    expect(check.status).toBe('warn');
    expect(check.message).toStartWith('Backup verdict is not current: the database was unreadable during the check.');
  });
});

// ── Remote (untrusted) path: cache-only reader, zero git, zero engine ────────

describe('checkBackupCoverage — remote surface (no localOnly)', () => {
  test('no cache → ok, "not checked from this surface", engine untouched', async () => {
    const check = await checkBackupCoverage(makeThrowingEngine(), {});
    expect(check.name).toBe('backup_coverage');
    expect(check.status).toBe('warn');
    expect(check.message).toContain('not checked from this surface');
    expect(check.message).toContain('gbrain backup check');
  });

  test('warn cache → AGGREGATE-ONLY warn from cache; zero git subprocesses, zero engine calls', async () => {
    // Trust pin (D4): the cached asset id points at a REAL git repo dir. If
    // the remote path probed git or touched the engine, the throwing engine
    // stub would blow up. And the remote surface is aggregate-only: the
    // message carries COUNTS ('N of M'), never the asset id / local path.
    const repo = makeNoOriginRepo('real-repo-dir');
    saveBackupStatus(makeWarnCache(repo));

    const check = await checkBackupCoverage(makeThrowingEngine(), {});

    expect(check.name).toBe('backup_coverage');
    expect(check.status).toBe('warn');
    expect(check.message).toContain('1 of 1'); // aggregate counts
    expect(check.message).not.toContain(repo); // NEVER the asset id / local path
    expect(check.message).not.toContain('real-repo-dir');
    expect(check.message).toContain('gbrain backup status');

    const details = check.details as { note?: string; computed_by?: string; cache_age?: string };
    expect(details.note).toBe('cache-only (remote surface never probes git; aggregate counts only)');
    expect(details.computed_by).toBeUndefined(); // remote details drop provenance
    expect(typeof details.cache_age).toBe('string');
  });

  test.each([
    { label: 'dirty repo', asset: { state: 'dirty', detail: 'uncommitted changes', configured_remote: true }, reason: '1 dirty' },
    { label: 'remote set, nothing pushed', asset: { state: 'no_remote', configured_remote: true }, reason: '1 remote configured, nothing pushed' },
    { label: 'no remote at all', asset: { state: 'no_remote' }, reason: '1 no git remote' },
    { label: 'ok without remote evidence', asset: { state: 'ok', configured_remote: true }, reason: '1 remote not verified: not_checked' },
    { label: 'known unknown code', asset: { state: 'unknown', detail: 'not_a_git_repo' }, reason: '1 not_a_git_repo' },
    { label: 'free-text unknown detail', asset: { state: 'unknown', detail: 'ahead of origin/private-branch-name' }, reason: '1 unknown' },
  ] as const)('remote warn names reason counts only: $label', async ({ asset, reason }) => {
    saveBackupStatus({
      ...makeWarnCache('private-src-id'),
      totals: { assets: 2, no_remote: 0, unpushed: 0, failing: 0, recoverable_repos: 0, pages_at_risk: 0 },
      assets: [
        { kind: 'db_only', id: 'private-src-id', state: 'info', fix_argv: null },
        { kind: 'source_repo', id: 'private-src-id', fix_argv: null, ...asset },
      ],
    });

    const check = await checkBackupCoverage(makeThrowingEngine(), {});

    expect(check.status).toBe('warn');
    expect(check.message).toContain(`1 of 2 knowledge asset(s) lack verified recovery (${reason})`);
    expect(check.message).not.toContain('private-src-id');
    expect(check.message).not.toContain('private-branch-name');
  });

  test('stale cache with no blocking asset leads with the staleness, never "0 of N"', async () => {
    __setBackupIntervalForTests(60_000);
    saveBackupStatus({
      ...makeWarnCache('private-src-id'),
      checked_at: new Date(Date.now() - 10 * 60_000).toISOString(),
      overall: 'ok',
      totals: { assets: 1, no_remote: 0, unpushed: 0, failing: 0, recoverable_repos: 0, pages_at_risk: 0 },
      assets: [{ kind: 'db_only', id: 'private-src-id', state: 'info', fix_argv: null }],
    });

    const check = await checkBackupCoverage(makeThrowingEngine(), {});

    expect(check.status).toBe('warn');
    expect(check.message).toStartWith('Backup verdict is not current: the verdict is older than the check interval.');
    expect(check.message).not.toContain('0 of');
  });

  test('ok cache → ok from cache with the cache-only note', async () => {
    saveBackupStatus({
      ...makeWarnCache('unused'),
      overall: 'ok',
      totals: { assets: 1, no_remote: 0, unpushed: 0, failing: 0, recoverable_repos: 1, pages_at_risk: 0 },
      assets: [{ kind: 'source_repo', id: 'unused', state: 'ok' }],
    });
    const check = await checkBackupCoverage(makeThrowingEngine(), {});
    expect(check.status).toBe('warn');
    expect(check.message).toContain('(1 remote not verified: not_checked)');
    expect((check.details as { totals: BackupStatus['totals'] }).totals.recoverable_repos).toBe(0);
    expect((check.details as { note?: string }).note).toBe(
      'cache-only (remote surface never probes git; aggregate counts only)',
    );
  });
});

// ── Kill switch ───────────────────────────────────────────────────────────────

describe('checkBackupCoverage — GBRAIN_BACKUP_CHECK=0', () => {
  test('disabled → ok with "disabled" message, no probes, no engine, no cache write', async () => {
    process.env.GBRAIN_BACKUP_CHECK = '0';
    const check = await checkBackupCoverage(makeThrowingEngine(), { localOnly: true });
    expect(check.name).toBe('backup_coverage');
    expect(check.status).toBe('ok');
    expect(check.message).toContain('disabled');
    // Early return: no compute ran, so nothing was persisted.
    expect(existsSync(statusFile)).toBe(false);
  });

  test('disabled shadows even a stale warn cache on the remote surface', async () => {
    process.env.GBRAIN_BACKUP_CHECK = '0';
    saveBackupStatus(makeWarnCache('anything'));
    const check = await checkBackupCoverage(makeThrowingEngine(), {});
    expect(check.status).toBe('ok');
    expect(check.message).toContain('disabled');
  });
});

// ── Local catch branch: getBackupStatus rethrows, checker degrades to warn ───

describe('checkBackupCoverage — localOnly catch branch', () => {
  test('compute throws with NO cache → warn "backup coverage unreadable", nothing persisted', async () => {
    // Verified against the source: a throwing engine alone only DEGRADES the
    // verdict (loadAllSources/countLivePages catch internally — no throw). To
    // make getBackupStatus itself throw through the public API, inject an
    // Invalid Date (checked_at serialization throws mid-compute — the same
    // idiom as backup-coverage.serial.test.ts). With NO cache to fall back
    // to, getBackupStatus rethrows and the checker's try/catch owns it.
    const throwing = {
      kind: 'pglite',
      executeRaw: async () => {
        throw new Error('engine down');
      },
    } as unknown as BrainEngine;

    expect(existsSync(statusFile)).toBe(false);
    const check = await checkBackupCoverage(throwing, {
      localOnly: true,
      now: new Date('not-a-date'),
    });

    // E1: the generic unreadable warn goes through checkError — the error
    // detail is kept and the check says why it carries no fix.
    expect(check).toEqual({
      name: 'backup_coverage',
      status: 'warn',
      message: 'Could not read backup coverage: Invalid Date',
      fix_unavailable_reason: 'check_errored',
    });
    // The failed compute never persisted anything (no clobber, no cache).
    expect(existsSync(statusFile)).toBe(false);
  });

  test('broken compute WITH a cache → the cached verdict is returned, not the unreadable warn', async () => {
    // The sibling path: with a cache present, getBackupStatus never surfaces
    // the failure (a fresh cache short-circuits; even a failed compute falls
    // back to the prior verdict) — the checker renders the cached verdict.
    const cache = makeWarnCache('cached-asset-src');
    saveBackupStatus(cache);
    const throwing = {
      kind: 'pglite',
      executeRaw: async () => {
        throw new Error('engine down');
      },
    } as unknown as BrainEngine;

    const check = await checkBackupCoverage(throwing, {
      localOnly: true,
      now: new Date('not-a-date'),
    });

    expect(check.status).toBe('warn');
    expect(check.message).toContain('cached-asset-src'); // local surface names assets
    expect(check.message).not.toBe('backup coverage unreadable');
  });
});

// ── GBRA-585 item 7: the young-brain count and the full-backup fix per engine ─

/** Engine stub answering the maturity count before the sources/pages listings (its SQL names both tables). */
function makeCountingEngine(kind: 'pglite' | 'postgres', sources: Array<{ id: string; local_path: string }>, pages: number, facts: number): BrainEngine {
  const listing = makeEngine(sources, pages);
  return {
    kind,
    executeRaw: async (sql: string) => {
      if (/AS pages/i.test(sql)) return [{ pages, facts, since: new Date(Date.now() - 60_000).toISOString() }];
      return listing.executeRaw(sql);
    },
  } as unknown as BrainEngine;
}

/** A verdict cached when the brain was empty (init), with remote evidence fresh enough to be reused. */
function cacheFromEmptyBrain(assetId: string): BackupStatus {
  const now = new Date().toISOString();
  return {
    ...makeWarnCache(assetId),
    checked_at: now,
    remote_check_at: now,
    totals: { assets: 1, no_remote: 0, unpushed: 0, failing: 0, recoverable_repos: 0, pages_at_risk: 0 },
    assets: [{ kind: 'source_repo', id: assetId, state: 'unknown', detail: 'not_a_git_repo', fix_argv: null }],
    maturity: { items: 0, since: new Date(Date.now() - 60_000).toISOString() },
  };
}

describe('checkBackupCoverage — GBRA-585 item 7', () => {
  test('a cached verdict from the empty brain reports the current page+fact count, not 0', async () => {
    const plain = join(tmp, 'default');
    mkdirSync(plain, { recursive: true });
    saveBackupStatus(cacheFromEmptyBrain('default'));

    const young = await checkBackupCoverage(makeCountingEngine('pglite', [{ id: 'default', local_path: plain }], 20, 3), { localOnly: true });
    expect(young.message).toContain('the brain holds 23 page(s)+fact(s)');

    const full = await checkBackupCoverage(makeCountingEngine('pglite', [{ id: 'default', local_path: plain }], 27, 7), { localOnly: true });
    expect(full.status).toBe('warn');
    expect(full.message).not.toContain('holds 0 page(s)');
  });

  test('PGLite: a content directory with no git repo is fixed by gbrain backup create, never gbrain export', async () => {
    const plain = join(tmp, 'default');
    mkdirSync(plain, { recursive: true });
    const check = await checkBackupCoverage(makeCountingEngine('pglite', [{ id: 'default', local_path: plain }], 27, 7), { localOnly: true });
    expect(check.status).toBe('warn');
    expect(check.fix?.argv).toEqual(['gbrain', 'backup', 'create', '--output', '<BACKUP_FILE>']);
  });

  test('Postgres: the same asset is fixed by a pg_dump of the brain database, never gbrain export', async () => {
    const plain = join(tmp, 'default');
    mkdirSync(plain, { recursive: true });
    const check = await checkBackupCoverage(makeCountingEngine('postgres', [{ id: 'default', local_path: plain }], 27, 7), { localOnly: true });
    expect(check.status).toBe('warn');
    expect(check.fix?.argv?.[0]).toBe('pg_dump');
    expect(check.fix?.actor).toBe('host_admin');
    expect(check.fix?.user_message).toContain('pg_restore');
    expect(check.fix?.user_message).toContain('`gbrain export` is not a backup');
    expect(check.fix?.argv).not.toContain('export');
  });
});