Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
21.0 KB
Raw Blame
/**
 * Tests for src/core/advisor/collect-backup-coverage.ts — the advisor
 * collector that surfaces the monthly backup-coverage verdict.
 *
 * Local runs (ctx.remote === false) recompute through getBackupStatus with
 * real git probes against tmp fixture repos and emit per-asset findings,
 * gated as one batch through backupNagGate. Remote runs (ctx.remote === true)
 * are cache-readers only: one aggregate finding, no source ids, no local
 * paths, and NEVER a nag-state write.
 *
 * Isolation: tmp GBRAIN_HOME (configDir() appends '.gbrain') plus the
 * status-file __set...ForTests path seams, so the real ~/.gbrain is never
 * touched. No mock.module → plain .test.ts (not serial).
 */
import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
import { execFileSync } from 'node:child_process';
import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';

import { collectBackupCoverage } from '../src/core/advisor/collect-backup-coverage.ts';
import { COLLECTORS } from '../src/core/advisor/run.ts';
import type { AdvisorContext } from '../src/core/advisor/types.ts';
import {
  BACKUP_STATUS_SCHEMA_VERSION,
  __setBackupIntervalForTests,
  __setBackupNagStatePathForTests,
  __setBackupStatusPathForTests,
  loadBackupNagState,
  saveBackupStatus,
  type BackupStatus,
} from '../src/core/backup/status-file.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 statusPath: string;
let nagPath: string;

beforeEach(() => {
  tmp = realpathSync(mkdtempSync(join(tmpdir(), 'gb-adv-bak-')));
  saved = {};
  for (const k of ENV_KEYS) {
    saved[k] = process.env[k];
    delete process.env[k];
  }
  process.env.GBRAIN_HOME = tmp; // configDir() → tmp/.gbrain (receipt, bridge state, config all isolated)
  statusPath = join(tmp, 'backup-status.json');
  nagPath = join(tmp, 'backup-nag-state.json');
  __setBackupStatusPathForTests(statusPath);
  __setBackupNagStatePathForTests(nagPath);
});

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 });
});

// ── Fixture helpers ──────────────────────────────────────────────────────────

function git(cwd: string, args: string[]): void {
  execFileSync(
    'git',
    ['-c', '[email protected]', '-c', 'user.name=t', ...args],
    { cwd, stdio: ['ignore', 'ignore', 'ignore'] },
  );
}

/** A git repo with one commit and NO origin remote. */
function makeNoRemoteRepo(name: string): string {
  const dir = join(tmp, name);
  mkdirSync(dir, { recursive: true });
  git(dir, ['init', '-q', '-b', 'main']);
  writeFileSync(join(dir, 'README.md'), 'hello\n');
  git(dir, ['add', '.']);
  git(dir, ['commit', '-q', '-m', 'init', '--no-gpg-sign']);
  return dir;
}

/** A repo with an origin (local bare), pushed, then one commit ahead. */
function makeUnpushedRepo(name: string): string {
  const dir = makeNoRemoteRepo(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']);
  writeFileSync(join(dir, 'extra.md'), 'ahead\n');
  git(dir, ['add', '.']);
  git(dir, ['commit', '-q', '-m', 'ahead', '--no-gpg-sign']);
  return dir;
}

interface SourceFixture {
  id: string;
  local_path: string;
}

/** Minimal engine stub: sources + pages queries via executeRaw. */
function makeEngine(opts: { sources?: SourceFixture[]; pageCount?: number } = {}) {
  const calls: string[] = [];
  const engine = {
    kind: 'pglite',
    executeRaw: async (sql: string) => {
      calls.push(sql);
      if (/from\s+sources/i.test(sql)) {
        return (opts.sources ?? []).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('2026-01-01T00:00:00Z'),
          archived: false,
          newest_content_at: null,
        }));
      }
      if (/from\s+pages/i.test(sql)) return [{ n: opts.pageCount ?? 0 }];
      return [];
    },
  };
  return { engine: engine as unknown as AdvisorContext['engine'], calls };
}

function ctx(
  engine: AdvisorContext['engine'],
  over: Partial<AdvisorContext> = {},
): AdvisorContext {
  return {
    engine,
    config: {} as AdvisorContext['config'],
    version: '0.0.0',
    workspace: null,
    skillsDir: null,
    now: new Date('2026-06-01T00:00:00Z'),
    remote: false,
    ...over,
  };
}

/** A crafted warn cache for the remote (cache-reader) tests. */
function warnCache(over: Partial<BackupStatus> = {}): BackupStatus {
  return {
    schema_version: BACKUP_STATUS_SCHEMA_VERSION,
    checked_at: '2026-06-01T00:00:00Z',
    gbrain_version: '0.0.0',
    interval_days: 30,
    computed_by: 'cli',
    overall: 'warn',
    totals: { assets: 5, no_remote: 2, unpushed: 0, failing: 0, recoverable_repos: 3, pages_at_risk: 0 },
    assets: [
      {
        kind: 'source_repo',
        id: 'xylophone-secret-source-991',
        state: 'no_remote',
        detail: 'lives at /tmp/zzz-secret-local-path/notes',
        fix_argv: null,
      },
      {
        kind: 'source_repo',
        id: 'quux-secret-source-992',
        state: 'no_remote',
        detail: 'fix: git remote add origin <url>',
        fix_argv: null,
      },
    ],
    ...over,
  };
}

// ── 1. Local ctx (remote:false) — per-asset findings ─────────────────────────

describe('collectBackupCoverage local (remote:false)', () => {
  test('#5505: a non-Git source path holds the warn → one backup_recovery_unverified finding naming it', async () => {
    const plain = join(tmp, 'plain-dir');
    mkdirSync(plain, { recursive: true });
    const { engine } = makeEngine({ sources: [{ id: 'plain-src', local_path: plain }], pageCount: 0 });

    const findings = await collectBackupCoverage.collect(ctx(engine));

    const f = findings.find((x) => x.id === 'backup_recovery_unverified');
    expect(f?.severity).toBe('warn');
    expect(f?.title).toBe('1 knowledge asset(s) lack verified recovery: plain-src (not_a_git_repo).');
  });

  test('no-remote source repo → backup_source_no_remote:<id> warn with the recipe; unpushed repo → backup_unpushed_work info', async () => {
    const noRemote = makeNoRemoteRepo('zebra-repo');
    const unpushed = makeUnpushedRepo('yak-repo');
    const { engine } = makeEngine({
      sources: [
        { id: 'zebra-no-remote-src', local_path: noRemote },
        { id: 'yak-unpushed-src', local_path: unpushed },
      ],
      pageCount: 0,
    });

    const findings = await collectBackupCoverage.collect(ctx(engine));

    const noRemoteFinding = findings.find((f) => f.id === 'backup_source_no_remote:zebra-no-remote-src');
    expect(noRemoteFinding).toBeDefined();
    expect(noRemoteFinding?.severity).toBe('warn');
    expect(noRemoteFinding?.title).toContain('zebra-no-remote-src');
    // The recipe detail (plain repo, not bootstrap-initialized → argv null).
    expect(noRemoteFinding?.detail).toContain('git remote add origin <url>');
    expect(noRemoteFinding?.detail).toContain('gbrain sources harden');
    expect(noRemoteFinding?.fix.command_argv).toBeNull();

    const unpushedFinding = findings.find((f) => f.id === 'backup_unpushed_work');
    expect(unpushedFinding).toBeDefined();
    expect(unpushedFinding?.severity).toBe('info');
    expect(unpushedFinding?.title).toContain('1 repo(s)');
    expect(unpushedFinding?.detail).toContain('yak-unpushed-src');
    expect(unpushedFinding?.detail).toContain('1 commit(s) ahead of origin/main');

    // Batch discipline: every finding is ask_user + collector-stamped.
    expect(findings.length).toBeGreaterThan(0);
    for (const f of findings) {
      expect(f.ask_user).toBe(true);
      expect(f.collector).toBe('backup-coverage');
    }
  });

  test('receipt-less DB-only brain (pages, no sources, no workspace) → backup_db_content_unbacked warn', async () => {
    const { engine } = makeEngine({ sources: [], pageCount: 42 });

    const findings = await collectBackupCoverage.collect(ctx(engine));

    expect(findings).toHaveLength(1);
    const f = findings[0]!;
    expect(f.id).toBe('backup_db_content_unbacked');
    expect(f.severity).toBe('warn');
    expect(f.detail).toContain('42 pages');
    expect(f.fix.command_argv).toEqual(['gbrain', 'bootstrap', 'repo']);
    expect(f.ask_user).toBe(true);
    expect(f.collector).toBe('backup-coverage');
  });
});

// ── 2 + 3. Remote ctx (remote:true) — cache-reader, aggregate-only ───────────

describe('collectBackupCoverage remote (remote:true)', () => {
  test('warn cache → exactly ONE aggregate finding; no source ids, no local paths, no nag-state write', async () => {
    saveBackupStatus(warnCache());
    // Remote must never touch the engine (cache-only read).
    const engine = {
      executeRaw: async () => {
        throw new Error('remote collect must not query the engine');
      },
    } as unknown as AdvisorContext['engine'];

    const findings = await collectBackupCoverage.collect(ctx(engine, { remote: true }));

    expect(findings).toHaveLength(1);
    const f = findings[0]!;
    expect(f.id).toBe('backup_coverage_aggregate');
    expect(f.severity).toBe('warn');
    expect(f.title).toContain('2 of 5');
    expect(f.fix.command_argv).toBeNull();
    expect(f.ask_user).toBe(true);
    expect(f.collector).toBe('backup-coverage');

    // amendment-29 discipline: aggregate wording ONLY — never a source id or
    // a local path from the cached verdict.
    const blob = JSON.stringify(findings);
    expect(blob).not.toContain('xylophone-secret-source-991');
    expect(blob).not.toContain('quux-secret-source-992');
    expect(blob).not.toContain('/tmp/zzz-secret-local-path');
    expect(blob).not.toContain('zzz-secret-local-path');

    // No nag writes on remote — the state file must not exist.
    expect(existsSync(nagPath)).toBe(false);
  });

  test('#5505: warn cache held only by a dirty repo → reason counts, never "0 of N ... no git remote"', async () => {
    saveBackupStatus(
      warnCache({
        totals: { assets: 2, no_remote: 0, unpushed: 0, failing: 0, recoverable_repos: 0, pages_at_risk: 0 },
        assets: [{ kind: 'source_repo', id: 'xylophone-secret-source-991', state: 'dirty', detail: 'uncommitted changes', fix_argv: null }],
      }),
    );
    const engine = { executeRaw: async () => { throw new Error('remote collect must not query the engine'); } } as unknown as AdvisorContext['engine'];

    const [f] = await collectBackupCoverage.collect(ctx(engine, { remote: true }));

    expect(f?.title).toStartWith('1 of 2 knowledge assets lack verified recovery (1 dirty)');
    expect(f?.title).not.toContain('no git remote');
    expect(JSON.stringify(f)).not.toContain('xylophone-secret-source-991');
  });

  test('ok cache → zero findings and still no nag write', async () => {
    saveBackupStatus(
      warnCache({
        overall: 'ok',
        totals: { assets: 1, no_remote: 0, unpushed: 0, failing: 0, recoverable_repos: 1, pages_at_risk: 0 },
        assets: [{ kind: 'source_repo', id: 'fine-src', state: 'ok', verification: { state: 'verified', checked_at: '2026-06-01T00:00:00Z' } }],
      }),
    );
    const { engine } = makeEngine();
    const findings = await collectBackupCoverage.collect(ctx(engine, { remote: true }));
    expect(findings).toEqual([]);
    expect(existsSync(nagPath)).toBe(false);
  });

  test('NO cache → zero findings', async () => {
    expect(existsSync(statusPath)).toBe(false);
    const { engine } = makeEngine();
    const findings = await collectBackupCoverage.collect(ctx(engine, { remote: true }));
    expect(findings).toEqual([]);
    expect(existsSync(nagPath)).toBe(false);
  });
});

// ── #6942: the remote branch reads the cache through currentBackupEvidence ──

describe('collectBackupCoverage remote — cached evidence age (#6942)', () => {
  const NOW = Date.parse('2026-06-01T00:00:00Z');
  const iso = (ms: number) => new Date(ms).toISOString();
  const hour = 60 * 60 * 1000;
  function verifiedOkCache(verifiedAt: number, over: Partial<BackupStatus> = {}): BackupStatus {
    return warnCache({
      overall: 'ok',
      checked_at: iso(verifiedAt),
      totals: { assets: 1, no_remote: 0, unpushed: 0, failing: 0, recoverable_repos: 1, pages_at_risk: 0 },
      assets: [{
        kind: 'source_repo',
        id: 'xylophone-secret-source-991',
        state: 'ok',
        verification: { state: 'verified', checked_at: iso(verifiedAt) },
      }],
      ...over,
    });
  }
  const noEngine = { executeRaw: async () => { throw new Error('remote collect must not query the engine'); } } as unknown as AdvisorContext['engine'];

  test('fresh verified proof (10 minutes old) → zero findings', async () => {
    saveBackupStatus(verifiedOkCache(NOW - 10 * 60 * 1000));
    expect(await collectBackupCoverage.collect(ctx(noEngine, { remote: true }))).toEqual([]);
    expect(existsSync(nagPath)).toBe(false);
  });

  test('expired verified proof (2 hours old) under a cached ok → aggregate warn naming the stale remote check', async () => {
    saveBackupStatus(verifiedOkCache(NOW - 2 * hour));
    const findings = await collectBackupCoverage.collect(ctx(noEngine, { remote: true }));
    expect(findings).toHaveLength(1);
    expect(findings[0]?.id).toBe('backup_coverage_aggregate');
    expect(findings[0]?.severity).toBe('warn');
    expect(findings[0]?.title).toStartWith('1 of 1 knowledge assets lack verified recovery (1 remote not verified: stale)');
    expect(JSON.stringify(findings)).not.toContain('xylophone-secret-source-991');
    expect(existsSync(nagPath)).toBe(false);
  });

  test('future-dated cache and proof → aggregate warn, never trusted as ok', async () => {
    saveBackupStatus(verifiedOkCache(NOW + 48 * hour));
    const findings = await collectBackupCoverage.collect(ctx(noEngine, { remote: true }));
    expect(findings).toHaveLength(1);
    expect(findings[0]?.id).toBe('backup_coverage_aggregate');
    expect(findings[0]?.title).toContain('remote not verified: stale');
  });

  test('degraded cache with a fresh proof → aggregate warn', async () => {
    saveBackupStatus(verifiedOkCache(NOW - 10 * 60 * 1000, { degraded: true }));
    const findings = await collectBackupCoverage.collect(ctx(noEngine, { remote: true }));
    expect(findings).toHaveLength(1);
    expect(findings[0]?.id).toBe('backup_coverage_aggregate');
    expect(findings[0]?.severity).toBe('warn');
  });
});

// ── 4. Nag ceiling — 3 surfaced batches per verdict, then quiet ──────────────

describe('collectBackupCoverage nag ceiling', () => {
  test('4 runs spaced +25h in the same month: 3 surfaced batches, then []', async () => {
    const noRemote = makeNoRemoteRepo('ceiling-repo');
    const { engine } = makeEngine({
      sources: [{ id: 'ceiling-src', local_path: noRemote }],
      pageCount: 0,
    });

    const t0 = Date.parse('2026-06-01T00:00:00Z');
    const hour = 60 * 60 * 1000;
    const runs: number[] = [];
    for (let i = 0; i < 4; i++) {
      // +25h between runs clears the 24h cross-channel dampener while every
      // run stays inside June (same global month bucket) and inside the 30d
      // cache interval (one compute, constant verdict fingerprint).
      const now = new Date(t0 + i * 25 * hour);
      const findings = await collectBackupCoverage.collect(ctx(engine, { now }));
      runs.push(findings.length);
    }

    expect(runs[0]).toBeGreaterThan(0);
    expect(runs[1]).toBeGreaterThan(0);
    expect(runs[2]).toBeGreaterThan(0);
    // Per-channel ceiling (3 per pseudo-version) AND the 3/month global cap
    // are both spent — the 4th call is gate-suppressed.
    expect(runs[3]).toBe(0);

    // The per-channel entry confirms suppression rather than an accident.
    const state = loadBackupNagState();
    const entry = state.entries.find((e) => e.pack_name === 'advisor');
    expect(entry).toBeDefined();
    expect(entry?.declined_count).toBe(3);
    expect(entry?.suppressed).toBe(true);
    expect(state.global_shown_count).toBe(3);
    expect(state.global_month).toBe('2026-06');
  });
});

// ── Workspace + db_only findings (local branch) ──────────────────────────────

/** Install receipt at configDir()/bootstrap/receipt.json (readReceipt shape). */
function writeReceipt(ws: string, extra: Record<string, unknown> = {}): void {
  const dir = join(tmp, '.gbrain', 'bootstrap');
  mkdirSync(dir, { recursive: true });
  writeFileSync(
    join(dir, 'receipt.json'),
    JSON.stringify(
      {
        receipt_version: 1,
        workspace_dir: ws,
        source_id: 'workspace',
        agent_name: 'agent-example',
        created_at: new Date().toISOString(),
        created_by: 'test',
        brain_created_by_bootstrap: false,
        created_paths: [],
        registrations: [],
        ...extra,
      },
      null,
      2,
    ),
  );
}

describe('collectBackupCoverage local — workspace and db_only findings', () => {
  test('receipt without repo_url → backup_workspace_no_repo warn, no single-command fix (ambiguous between repo/attach)', async () => {
    const ws = join(tmp, 'ws-no-repo');
    mkdirSync(ws, { recursive: true });
    writeReceipt(ws); // no repo_url → bootstrap_workspace no_remote asset

    const { engine } = makeEngine({ sources: [], pageCount: 0 });
    const findings = await collectBackupCoverage.collect(ctx(engine));

    expect(findings).toHaveLength(1);
    const f = findings[0]!;
    expect(f.id).toBe('backup_workspace_no_repo');
    expect(f.severity).toBe('warn');
    expect(f.title).toContain('workspace has no private repo');
    expect(f.detail).toContain('no private repo yet');
    // No default fallback: this check can't tell an empty origin (needs
    // `bootstrap repo`) from an already-pushed out-of-band one (needs
    // `bootstrap attach`) without a git subprocess — see coverage.ts.
    expect(f.fix.command_argv).toBeNull();
    expect(f.ask_user).toBe(true);
    expect(f.collector).toBe('backup-coverage');
  });

  test('db_only source alongside a no-remote repo → backup_db_only_caveat info rides the warn batch', async () => {
    const noRemote = makeNoRemoteRepo('plain-repo');
    const tiered = makeNoRemoteRepo('tiered-repo');
    writeFileSync(join(tiered, 'gbrain.yml'), 'storage:\n  db_only:\n    - private/\n');

    const { engine } = makeEngine({
      sources: [
        { id: 'plain-src', local_path: noRemote },
        { id: 'tiered-src', local_path: tiered },
      ],
      pageCount: 0,
    });
    const findings = await collectBackupCoverage.collect(ctx(engine));

    const caveat = findings.find((f) => f.id === 'backup_db_only_caveat');
    expect(caveat).toBeDefined();
    expect(caveat?.severity).toBe('info');
    expect(caveat?.title).toContain('db_only');
    expect(caveat?.detail).toContain('undeclared_db_only_pages');
    expect(caveat?.fix.command_argv).toBeNull();
    // The warn batch it rides on is present too (both repos lack an origin).
    expect(findings.some((f) => f.id === 'backup_source_no_remote:plain-src')).toBe(true);
    expect(findings.some((f) => f.id === 'backup_source_no_remote:tiered-src')).toBe(true);
  });
});

// ── Kill switch: disabled → [] on BOTH branches ──────────────────────────────

describe('collectBackupCoverage — GBRAIN_BACKUP_CHECK=0', () => {
  test('disabled → [] on local AND remote branches even with a warn cache; engine untouched, no nag write', async () => {
    process.env.GBRAIN_BACKUP_CHECK = '0';
    saveBackupStatus(warnCache()); // a stale warn cache must go silent too

    // Any engine touch (compute attempt) blows the test up.
    const throwing = {
      executeRaw: async () => {
        throw new Error('disabled collect must not query the engine');
      },
    } as unknown as AdvisorContext['engine'];

    const local = await collectBackupCoverage.collect(ctx(throwing));
    expect(local).toEqual([]);

    const remote = await collectBackupCoverage.collect(ctx(throwing, { remote: true }));
    expect(remote).toEqual([]);

    expect(existsSync(nagPath)).toBe(false); // no nag-state write on either branch
  });
});

// ── 5. COLLECTORS registration pin ───────────────────────────────────────────

describe('advisor registration', () => {
  test('COLLECTORS includes backup-coverage', () => {
    expect(COLLECTORS.some((c) => c.id === 'backup-coverage')).toBe(true);
    expect(collectBackupCoverage.id).toBe('backup-coverage');
  });
});