Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
11.6 KB
Raw Blame
/**
 * v0.39.3.0 Phase 3c — capture CLI write-side test surface.
 *
 * Covers the pure helpers introduced/changed in capture.ts as a unit
 * test (not the full runCapture orchestration; that's exercised via
 * the existing tests + the E2E ingest-capture-provenance suite).
 * Hermetic — no engine, no DB.
 *
 * Findings exercised here:
 *   CV9  normalizeForHash — separates hash normalization from storage
 *   CV8  receipt hash from rawBody (the slug + content_hash use the
 *        normalized body, not the timestamp-bearing frontmatter)
 *   CV10 detectBinaryNullByte — first-8KB sniff, deterministic fixtures
 *   A2   maybeRewriteSourceFkError — friendly hint pattern (both engines)
 *
 * runCapture's branching (thin-client rejection of --source, source
 * resolver, exit-1 paths) is verified by exercising the helpers and
 * by the existing tests; integration is covered by the E2E test added
 * in test/e2e/ingest-capture-provenance.test.ts.
 */

import { describe, test, expect } from 'bun:test';
import { __testing as captureTesting } from '../src/commands/capture.ts';
import { computeContentHash } from '../src/core/ingestion/types.ts';
import { caught, envelopeFor } from './helpers/agent-envelope.ts';

const { detectBinaryNullByte, detectBinarySignature, normalizeForHash, maybeRewriteSourceFkError } = captureTesting;

describe('CV10 — binary file guard (detectBinaryNullByte)', () => {
  test('returns -1 on plain ASCII', () => {
    expect(detectBinaryNullByte(Buffer.from('hello world'))).toBe(-1);
  });

  test('returns -1 on UTF-8 with CJK (測試)', () => {
    expect(detectBinaryNullByte(Buffer.from('測試 brain content'))).toBe(-1);
  });

  test('returns -1 on UTF-8 with emoji (🧠🔥)', () => {
    expect(detectBinaryNullByte(Buffer.from('thinking 🧠🔥 hot'))).toBe(-1);
  });

  test('returns -1 on UTF-8 BOM-prefixed text', () => {
    const bom = Buffer.from([0xef, 0xbb, 0xbf]);
    const text = Buffer.from('# heading\n\nbody');
    expect(detectBinaryNullByte(Buffer.concat([bom, text]))).toBe(-1);
  });

  test('returns offset on NUL byte at start', () => {
    const bytes = Buffer.from([0x00, 0x68, 0x69]);
    expect(detectBinaryNullByte(bytes)).toBe(0);
  });

  test('returns offset on NUL byte mid-buffer', () => {
    const bytes = Buffer.from('hello\x00world');
    expect(detectBinaryNullByte(bytes)).toBe(5);
  });

  test('returns offset on PNG magic bytes (NUL at byte 0)', () => {
    // PNG header has multiple NUL bytes — the first appears at offset 8
    // (after the 8-byte signature 0x89 0x50 0x4e 0x47 0x0d 0x0a 0x1a 0x0a,
    // the IHDR chunk length 0x00 0x00 0x00 0x0d follows).
    const png = Buffer.from([
      0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, // PNG signature
      0x00, 0x00, 0x00, 0x0d,                          // IHDR length
    ]);
    expect(detectBinaryNullByte(png)).toBe(8);
  });

  test('caps scan at 8KB (NUL at offset 8192 NOT detected)', () => {
    const bytes = Buffer.alloc(10_000, 0x41); // 'A' bytes
    bytes[8192] = 0x00; // beyond the 8KB ceiling
    expect(detectBinaryNullByte(bytes)).toBe(-1);
  });

  test('detects NUL at exactly offset 8191 (within scan window)', () => {
    const bytes = Buffer.alloc(10_000, 0x41);
    bytes[8191] = 0x00;
    expect(detectBinaryNullByte(bytes)).toBe(8191);
  });

  test('empty buffer returns -1', () => {
    expect(detectBinaryNullByte(Buffer.alloc(0))).toBe(-1);
  });
});

describe('magic-byte binary guard (detectBinarySignature)', () => {
  // The regression that motivated this guard: a small ASCII-armored PDF with
  // ZERO NUL bytes anywhere. It passed the CV10 NUL scan, was UTF-8-decoded to
  // U+FFFD mojibake, and got stored as a page body titled '%PDF-1.4' — with the
  // document's real text (inside FlateDecode streams) silently lost, while
  // `capture` reported success.
  test('rejects a NUL-free PDF that the NUL scan cannot catch', () => {
    const pdf = Buffer.from('%PDF-1.4\n1 0 obj\n<</Type/Catalog>>\nendobj\n');
    expect(pdf.includes(0)).toBe(false);        // the exact hole: no NUL to find
    expect(detectBinaryNullByte(pdf)).toBe(-1); // ...so the old guard passes it
    expect(detectBinarySignature(pdf)).toBe('PDF'); // ...and the new one stops it
  });

  test('detects common container formats', () => {
    const cases: Array<[Buffer, string]> = [
      [Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]), 'PNG'],
      [Buffer.from([0xff, 0xd8, 0xff, 0xe0]), 'JPEG'],
      [Buffer.from('GIF89a'), 'GIF'],
      [Buffer.from([0x50, 0x4b, 0x03, 0x04]), 'ZIP / OOXML (docx, xlsx, pptx)'],
      [Buffer.from([0x1f, 0x8b, 0x08]), 'gzip'],
      [Buffer.from([0x7f, 0x45, 0x4c, 0x46]), 'ELF executable'],
      [Buffer.from('SQLite format 3\0'), 'SQLite database'],
      [Buffer.from('OggS'), 'Ogg'],
      [Buffer.from([0x1a, 0x45, 0xdf, 0xa3]), 'Matroska / WebM'],
    ];
    for (const [buf, label] of cases) {
      expect(detectBinarySignature(buf)).toBe(label);
    }
  });

  test('matches signatures at non-zero offsets', () => {
    // MP4: 4-byte box size, then 'ftyp' at offset 4.
    const mp4 = Buffer.concat([Buffer.from([0x00, 0x00, 0x00, 0x18]), Buffer.from('ftypisom')]);
    expect(detectBinarySignature(mp4)).toBe('MP4 / MOV / HEIC');
    // RIFF containers are disambiguated by the tag at offset 8.
    const webp = Buffer.concat([Buffer.from('RIFF'), Buffer.from([0, 0, 0, 0]), Buffer.from('WEBP')]);
    expect(detectBinarySignature(webp)).toBe('WebP');
    const wav = Buffer.concat([Buffer.from('RIFF'), Buffer.from([0, 0, 0, 0]), Buffer.from('WAVE')]);
    expect(detectBinarySignature(wav)).toBe('WAV');
  });

  test('passes real text through, including the shapes that look risky', () => {
    const texts = [
      'hello world',
      '# A markdown heading\n\nBody text.',
      '測試 brain content',                        // multi-byte CJK
      'thinking 🧠🔥 hot',                         // emoji
      '# BOM-prefixed markdown',            // UTF-8 BOM
      '---\ntitle: T\ntype: note\n---\n\n# Body', // frontmatter
      'MZ is a two-letter prefix in a sentence.', // deliberately-omitted weak magic
      'BM is another one.',                       // deliberately-omitted weak magic
      'ID3 tags are metadata containers.',        // deliberately-omitted weak magic
      '%!PS-Adobe-3.0 is PostScript, which is text.',
    ];
    for (const t of texts) {
      expect(detectBinarySignature(Buffer.from(t))).toBeNull();
    }
  });

  test('handles buffers shorter than a signature without throwing', () => {
    expect(detectBinarySignature(Buffer.alloc(0))).toBeNull();
    expect(detectBinarySignature(Buffer.from('%PD'))).toBeNull(); // truncated PDF magic
    expect(detectBinarySignature(Buffer.from([0x89]))).toBeNull();
  });
});

describe('CV9 — normalizeForHash (trim + LF + NFKC)', () => {
  test('strips leading/trailing whitespace', () => {
    expect(normalizeForHash('  hello  ')).toBe('hello');
  });

  test('strips UTF-8 BOM', () => {
    expect(normalizeForHash('hello')).toBe('hello');
  });

  test('normalizes CRLF to LF', () => {
    expect(normalizeForHash('a\r\nb\r\nc')).toBe('a\nb\nc');
  });

  test('NFKC normalizes precomposed/decomposed Unicode (ñ)', () => {
    // U+00F1 (precomposed) vs U+006E + U+0303 (decomposed). NFKC unifies.
    const precomposed = 'mañana';
    const decomposed = 'mañana'; // ñ as n + combining tilde
    expect(normalizeForHash(precomposed)).toBe(normalizeForHash(decomposed));
  });

  test('does not modify already-clean text', () => {
    expect(normalizeForHash('clean text\nwith newlines')).toBe('clean text\nwith newlines');
  });

  test('whitespace-only input normalizes to empty', () => {
    expect(normalizeForHash('   \n\r\n\t  ')).toBe('');
  });
});

describe('CV8 — receipt hash stable across timestamp variations', () => {
  test('identical input text produces identical hash regardless of when called', () => {
    const text = 'remember to follow up on the X deal';
    const h1 = computeContentHash(normalizeForHash(text));
    // Simulate "captured at a different time" by re-calling
    const h2 = computeContentHash(normalizeForHash(text));
    expect(h1).toBe(h2);
  });

  test('hash differs for different content', () => {
    const h1 = computeContentHash(normalizeForHash('text A'));
    const h2 = computeContentHash(normalizeForHash('text B'));
    expect(h1).not.toBe(h2);
  });

  test('whitespace differences normalize to same hash (CV9 + CV8 interaction)', () => {
    const h1 = computeContentHash(normalizeForHash('  same text  '));
    const h2 = computeContentHash(normalizeForHash('same text'));
    expect(h1).toBe(h2);
  });

  test('CRLF vs LF line endings normalize to same hash', () => {
    const h1 = computeContentHash(normalizeForHash('line1\r\nline2'));
    const h2 = computeContentHash(normalizeForHash('line1\nline2'));
    expect(h1).toBe(h2);
  });
});

describe('A2 — maybeRewriteSourceFkError (friendly FK violation hint)', () => {
  test('rewrites the raw Postgres pages_source_id_fk message', () => {
    const err = new Error(
      'insert or update on table "pages" violates foreign key constraint "pages_source_id_fk"',
    );
    const hint = maybeRewriteSourceFkError(err, 'dept-x');
    expect(hint).toContain("source 'dept-x' is not registered");
    expect(hint).toContain('gbrain sources add dept-x');
    expect(hint).toContain('gbrain sources list');
  });

  test('rewrites a wrapped OperationError-style message containing the FK constraint name', () => {
    const err = new Error(
      'put_page failed: insert or update on table "pages" violates foreign key constraint "pages_source_id_fk"',
    );
    const hint = maybeRewriteSourceFkError(err, 'my-source');
    expect(hint).toContain("source 'my-source' is not registered");
  });

  test('rewrites a "foreign key constraint ... source" pattern (postgres.js wrapped)', () => {
    const err = new Error(
      'update or delete on table "sources" violates foreign key constraint',
    );
    expect(maybeRewriteSourceFkError(err, 'src-x')).toContain("source 'src-x' is not registered");
  });

  test('returns null on unrelated errors', () => {
    expect(maybeRewriteSourceFkError(new Error('connection timeout'), 'dept-x')).toBeNull();
    expect(maybeRewriteSourceFkError(new Error('syntax error'), 'dept-x')).toBeNull();
  });

  test('returns null when sourceId is undefined (no friendly hint possible without the source name)', () => {
    const err = new Error('pages_source_id_fk violation');
    expect(maybeRewriteSourceFkError(err, undefined)).toBeNull();
  });

  test('handles non-Error throws (string thrown directly)', () => {
    const hint = maybeRewriteSourceFkError('pages_source_id_fk constraint violation', 'foo');
    expect(hint).not.toBeNull();
    expect(hint).toContain("source 'foo'");
  });
});

describe('capture argument refusals name their own next step', () => {
  test('an unsupported option lists the accepted flags, offers the help and never echoes its value', async () => {
    const env = envelopeFor(await caught(() => captureTesting.parseArgs(['--token=synthetic-credential-value', 'note'])));
    expect(env).toMatchObject({ code: 'invalid_params', fix: { argv: ['gbrain', 'capture', '--help'], next: 'run' } });
    expect(env.suggestion).toContain('Remove --token; gbrain capture accepts --file');
    expect(JSON.stringify(env)).not.toContain('synthetic-credential-value');
  });

  test('a mutation flag without a UUID names where the value comes from', async () => {
    expect(envelopeFor(await caught(() => captureTesting.parseArgs(['--expected-revision']))).suggestion).toContain('gbrain get --json');
    expect(envelopeFor(await caught(() => captureTesting.parseArgs(['--request-id', '--json']))).suggestion).toContain('replays that request');
  });
});