@flowcodex/core 0.3.0

package/tests/events.test.ts

@@ -0,0 +1,340 @@
+import { describe, it, expect, vi } from 'vitest';
+import { EventBus, ScopedEventBus, type EventName } from '../src/kernel/events.js';
+
+describe('EventBus', () => {
+  describe('on + emit', () => {
+    it('delivers events to listeners', () => {
+      const bus = new EventBus();
+      const fn = vi.fn();
+      bus.on('session.started', fn);
+      bus.emit('session.started', { id: 'test-123' });
+      expect(fn).toHaveBeenCalledWith({ id: 'test-123' });
+    });
+
+    it('delivers to multiple listeners', () => {
+      const bus = new EventBus();
+      const fn1 = vi.fn();
+      const fn2 = vi.fn();
+      bus.on('session.started', fn1);
+      bus.on('session.started', fn2);
+      bus.emit('session.started', { id: 'x' });
+      expect(fn1).toHaveBeenCalled();
+      expect(fn2).toHaveBeenCalled();
+    });
+
+    it('returns an unsubscribe function', () => {
+      const bus = new EventBus();
+      const fn = vi.fn();
+      const unsub = bus.on('session.started', fn);
+      unsub();
+      bus.emit('session.started', { id: 'x' });
+      expect(fn).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('off', () => {
+    it('removes a specific listener', () => {
+      const bus = new EventBus();
+      const fn1 = vi.fn();
+      const fn2 = vi.fn();
+      bus.on('session.started', fn1);
+      bus.on('session.started', fn2);
+      bus.off('session.started', fn1);
+      bus.emit('session.started', { id: 'x' });
+      expect(fn1).not.toHaveBeenCalled();
+      expect(fn2).toHaveBeenCalled();
+    });
+  });
+
+  describe('once', () => {
+    it('fires only once', () => {
+      const bus = new EventBus();
+      const fn = vi.fn();
+      bus.once('session.started', fn);
+      bus.emit('session.started', { id: 'a' });
+      bus.emit('session.started', { id: 'b' });
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    it('unsubscribe before fire prevents it', () => {
+      const bus = new EventBus();
+      const fn = vi.fn();
+      const unsub = bus.once('session.started', fn);
+      unsub();
+      bus.emit('session.started', { id: 'x' });
+      expect(fn).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('onAny (wildcard)', () => {
+    it('receives all events', () => {
+      const bus = new EventBus();
+      const fn = vi.fn();
+      bus.onAny(fn);
+      bus.emit('session.started', { id: 'x' });
+      bus.emit('tool.started', { name: 'read', id: '1' });
+      expect(fn).toHaveBeenCalledTimes(2);
+      expect(fn).toHaveBeenNthCalledWith(1, 'session.started', { id: 'x' });
+    });
+
+    it('returns unsubscribe', () => {
+      const bus = new EventBus();
+      const fn = vi.fn();
+      const unsub = bus.onAny(fn);
+      unsub();
+      bus.emit('session.started', { id: 'x' });
+      expect(fn).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('onPattern', () => {
+    it('matches prefix.* events', () => {
+      const bus = new EventBus();
+      const fn = vi.fn();
+      bus.onPattern('provider.*', fn);
+      bus.emit('provider.text_delta', { text: 'hi' });
+      bus.emit('tool.started', { name: 'read', id: '1' });
+      expect(fn).toHaveBeenCalledTimes(1);
+      expect(fn).toHaveBeenCalledWith('provider.text_delta', { text: 'hi' });
+    });
+
+    it('* matches everything', () => {
+      const bus = new EventBus();
+      const fn = vi.fn();
+      bus.onPattern('*', fn);
+      bus.emit('session.started', { id: 'x' });
+      bus.emit('error', { err: new Error('e'), phase: 'test' });
+      expect(fn).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe('onRegex', () => {
+    it('matches by regex', () => {
+      const bus = new EventBus();
+      const fn = vi.fn();
+      bus.onRegex(/^ctx\./, fn);
+      bus.emit('ctx.pct', { load: 0.5, tokens: 100, maxContext: 200000 });
+      bus.emit('tool.started', { name: 'r', id: '1' });
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('emitCustom', () => {
+    it('delivers to wildcard only', () => {
+      const bus = new EventBus();
+      const fn = vi.fn();
+      bus.onAny(fn);
+      bus.emitCustom('my.custom.event', { data: 42 });
+      expect(fn).toHaveBeenCalledWith('my.custom.event', { data: 42 });
+    });
+
+    it('no-op when no wildcards', () => {
+      const bus = new EventBus();
+      expect(() => bus.emitCustom('custom', { x: 1 })).not.toThrow();
+    });
+  });
+
+  describe('listener exceptions are swallowed', () => {
+    it('does not throw when a listener throws', () => {
+      const bus = new EventBus();
+      bus.on('session.started', () => { throw new Error('boom'); });
+      const fn2 = vi.fn();
+      bus.on('session.started', fn2);
+      expect(() => bus.emit('session.started', { id: 'x' })).not.toThrow();
+      expect(fn2).toHaveBeenCalled();
+    });
+
+    it('logs to logger when set', () => {
+      const bus = new EventBus();
+      const logFn = vi.fn();
+      bus.setLogger({ error: logFn });
+      bus.on('session.started', () => { throw new Error('boom'); });
+      bus.emit('session.started', { id: 'x' });
+      expect(logFn).toHaveBeenCalled();
+    });
+  });
+
+  describe('listenerCount', () => {
+    it('counts listeners for a specific event', () => {
+      const bus = new EventBus();
+      bus.on('session.started', () => {});
+      bus.on('session.started', () => {});
+      bus.on('tool.started', () => {});
+      expect(bus.listenerCount('session.started')).toBe(2);
+      expect(bus.listenerCount('tool.started')).toBe(1);
+    });
+
+    it('counts all listeners when no event given', () => {
+      const bus = new EventBus();
+      bus.on('session.started', () => {});
+      bus.on('tool.started', () => {});
+      expect(bus.listenerCount()).toBe(2);
+    });
+  });
+
+  describe('hasListenerFor', () => {
+    it('returns true for named listeners', () => {
+      const bus = new EventBus();
+      bus.on('session.started', () => {});
+      expect(bus.hasListenerFor('session.started')).toBe(true);
+    });
+
+    it('returns true for wildcard matches', () => {
+      const bus = new EventBus();
+      bus.onPattern('session.*', () => {});
+      expect(bus.hasListenerFor('session.started')).toBe(true);
+    });
+
+    it('returns false when no listeners', () => {
+      const bus = new EventBus();
+      expect(bus.hasListenerFor('session.started')).toBe(false);
+    });
+  });
+
+  describe('clear', () => {
+    it('removes all listeners and wildcards', () => {
+      const bus = new EventBus();
+      bus.on('session.started', () => {});
+      bus.onAny(() => {});
+      bus.clear();
+      expect(bus.listenerCount()).toBe(0);
+      expect(bus.wildcardCount()).toBe(0);
+    });
+  });
+
+  describe('all 25 event types', () => {
+    it('EventMap has exactly 25 keys', () => {
+      const events: EventName[] = [
+        'session.started', 'session.ended', 'session.damaged',
+        'iteration.started', 'iteration.completed', 'iteration.limit_reached',
+        'provider.response', 'provider.text_delta', 'provider.thinking_delta',
+        'provider.tool_use_start', 'provider.tool_use_input_delta', 'provider.tool_use_stop',
+        'provider.stream_error', 'provider.retry', 'provider.error',
+        'tool.started', 'tool.progress', 'tool.confirm_needed', 'tool.executed',
+        'ctx.pct', 'ctx.max_context',
+        'token.threshold', 'token.accounted', 'token.cost_estimate_unavailable',
+        'error',
+      ];
+      expect(events).toHaveLength(25);
+      for (const ev of events) {
+        const fn = vi.fn();
+        const bus = new EventBus();
+        bus.on(ev, fn);
+        // just verify it compiles + registers without error
+        expect(bus.listenerCount(ev)).toBe(1);
+      }
+    });
+  });
+});
+
+describe('ScopedEventBus', () => {
+  it('tracks registrations', () => {
+    const bus = new ScopedEventBus();
+    bus.on('session.started', () => {});
+    bus.on('tool.started', () => {});
+    expect(bus.scopedListenerCount).toBe(2);
+  });
+
+  it('teardown removes all tracked listeners', () => {
+    const bus = new ScopedEventBus();
+    const fn = vi.fn();
+    bus.on('session.started', fn);
+    bus.teardown();
+    bus.emit('session.started', { id: 'x' });
+    expect(fn).not.toHaveBeenCalled();
+    expect(bus.scopedListenerCount).toBe(0);
+  });
+
+  it('teardown is idempotent', () => {
+    const bus = new ScopedEventBus();
+    bus.on('session.started', () => {});
+    bus.teardown();
+    expect(() => bus.teardown()).not.toThrow();
+  });
+
+  it('Symbol.dispose calls teardown', () => {
+    const bus = new ScopedEventBus();
+    bus.on('session.started', () => {});
+    bus[Symbol.dispose]();
+    expect(bus.scopedListenerCount).toBe(0);
+  });
+
+  it('once is tracked and cleaned on fire', () => {
+    const bus = new ScopedEventBus();
+    const fn = vi.fn();
+    bus.once('session.started', fn);
+    expect(bus.scopedListenerCount).toBe(1);
+    bus.emit('session.started', { id: 'x' });
+    expect(fn).toHaveBeenCalledTimes(1);
+    expect(bus.scopedListenerCount).toBe(0);
+  });
+
+  it('onAny is tracked', () => {
+    const bus = new ScopedEventBus();
+    bus.onAny(() => {});
+    expect(bus.scopedListenerCount).toBe(1);
+    bus.teardown();
+    expect(bus.scopedListenerCount).toBe(0);
+  });
+
+  it('onPattern is tracked', () => {
+    const bus = new ScopedEventBus();
+    bus.onPattern('tool.*', () => {});
+    expect(bus.scopedListenerCount).toBe(1);
+    bus.teardown();
+    expect(bus.scopedListenerCount).toBe(0);
+  });
+
+  it('manual unsub removes from tracking', () => {
+    const bus = new ScopedEventBus();
+    const unsub = bus.on('session.started', () => {});
+    expect(bus.scopedListenerCount).toBe(1);
+    unsub();
+    expect(bus.scopedListenerCount).toBe(0);
+  });
+});
+
+describe('v0.3.0 events', () => {
+  it('delivers permission.persisted with allow/deny action and scope', () => {
+    const bus = new EventBus();
+    const fn = vi.fn();
+    bus.on('permission.persisted', fn);
+    bus.emit('permission.persisted', {
+      action: 'allow',
+      tool: 'bash',
+      pattern: 'pnpm *',
+      scope: 'trust',
+    });
+    expect(fn).toHaveBeenCalledWith({
+      action: 'allow',
+      tool: 'bash',
+      pattern: 'pnpm *',
+      scope: 'trust',
+    });
+  });
+
+  it('delivers compaction.fired with before/after/level', () => {
+    const bus = new EventBus();
+    const fn = vi.fn();
+    bus.on('compaction.fired', fn);
+    bus.emit('compaction.fired', { before: 18000, after: 12000, level: 'soft', aggressive: false });
+    expect(fn).toHaveBeenCalledWith({ before: 18000, after: 12000, level: 'soft', aggressive: false });
+  });
+
+  it('delivers compaction.failed with reason and attemptedLevel', () => {
+    const bus = new EventBus();
+    const fn = vi.fn();
+    bus.on('compaction.failed', fn);
+    bus.emit('compaction.failed', { reason: 'noop below delta', attemptedLevel: 'soft' });
+    expect(fn).toHaveBeenCalledWith({ reason: 'noop below delta', attemptedLevel: 'soft' });
+  });
+
+  it('onPattern matches compaction.* for both compaction events', () => {
+    const bus = new EventBus();
+    const fn = vi.fn();
+    bus.onPattern('compaction.*', (_event, _payload) => fn());
+    bus.emit('compaction.fired', { before: 1, after: 1, level: 'soft', aggressive: false });
+    bus.emit('compaction.failed', { reason: 'x', attemptedLevel: 'hard' });
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+});

package/tests/fs-utils.test.ts

@@ -0,0 +1,164 @@
+import { describe, it, expect } from 'vitest';
+import {
+  atomicWrite,
+  isBinaryBuffer,
+  detectNewlineStyle,
+  normalizeToLf,
+  toStyle,
+  compileGlob,
+  unifiedDiff,
+  stripAnsi,
+} from '../src/utils/fs.js';
+import { promises as fsp } from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+
+describe('utils/fs', () => {
+  describe('atomicWrite', () => {
+    it('writes content to file', async () => {
+      const tmp = await fsp.mkdtemp(path.join(os.tmpdir(), 'fcx-fs-'));
+      const file = path.join(tmp, 'test.txt');
+      await atomicWrite(file, 'hello world');
+      const content = await fsp.readFile(file, 'utf8');
+      expect(content).toBe('hello world');
+      await fsp.rm(tmp, { recursive: true, force: true });
+    });
+
+    it('overwrites existing file', async () => {
+      const tmp = await fsp.mkdtemp(path.join(os.tmpdir(), 'fcx-fs-'));
+      const file = path.join(tmp, 'test.txt');
+      await atomicWrite(file, 'old');
+      await atomicWrite(file, 'new');
+      const content = await fsp.readFile(file, 'utf8');
+      expect(content).toBe('new');
+      await fsp.rm(tmp, { recursive: true, force: true });
+    });
+  });
+
+  describe('isBinaryBuffer', () => {
+    it('returns false for text buffer', () => {
+      expect(isBinaryBuffer(Buffer.from('hello world'))).toBe(false);
+    });
+
+    it('returns true for buffer with null byte', () => {
+      expect(isBinaryBuffer(Buffer.from([0x68, 0x00, 0x65]))).toBe(true);
+    });
+
+    it('returns false for empty buffer', () => {
+      expect(isBinaryBuffer(Buffer.alloc(0))).toBe(false);
+    });
+  });
+
+  describe('newline utils', () => {
+    it('detectNewlineStyle: LF', () => {
+      expect(detectNewlineStyle('line1\nline2')).toBe('lf');
+    });
+
+    it('detectNewlineStyle: CRLF', () => {
+      expect(detectNewlineStyle('line1\r\nline2')).toBe('crlf');
+    });
+
+    it('normalizeToLf: converts CRLF', () => {
+      expect(normalizeToLf('a\r\nb\r\nc')).toBe('a\nb\nc');
+    });
+
+    it('normalizeToLf: converts bare CR', () => {
+      expect(normalizeToLf('a\rb')).toBe('a\nb');
+    });
+
+    it('toStyle: LF stays LF', () => {
+      expect(toStyle('a\nb', 'lf')).toBe('a\nb');
+    });
+
+    it('toStyle: LF to CRLF', () => {
+      expect(toStyle('a\nb', 'crlf')).toBe('a\r\nb');
+    });
+
+    it('roundtrip: normalize then restore', () => {
+      const original = 'a\r\nb\r\nc';
+      const style = detectNewlineStyle(original);
+      const normalized = normalizeToLf(original);
+      const restored = toStyle(normalized, style);
+      expect(restored).toBe(original);
+    });
+  });
+
+  describe('compileGlob', () => {
+    it('matches simple filename', () => {
+      const re = compileGlob('*.ts');
+      expect(re.test('foo.ts')).toBe(true);
+      expect(re.test('foo.js')).toBe(false);
+    });
+
+    it('matches double-star recursively', () => {
+      const re = compileGlob('**/*.ts');
+      expect(re.test('src/foo.ts')).toBe(true);
+      expect(re.test('src/nested/deep/bar.ts')).toBe(true);
+      expect(re.test('foo.js')).toBe(false);
+    });
+
+    it('matches literal path', () => {
+      const re = compileGlob('src/index.ts');
+      expect(re.test('src/index.ts')).toBe(true);
+      expect(re.test('src/other.ts')).toBe(false);
+    });
+
+    it('matches single star within path segment', () => {
+      const re = compileGlob('src/*.ts');
+      expect(re.test('src/foo.ts')).toBe(true);
+      expect(re.test('src/nested/foo.ts')).toBe(false);
+    });
+
+    it('matches question mark', () => {
+      const re = compileGlob('foo?.ts');
+      expect(re.test('foo1.ts')).toBe(true);
+      expect(re.test('foo12.ts')).toBe(false);
+    });
+
+    it('escapes regex special chars', () => {
+      const re = compileGglob_safe('foo.bar');
+      expect(re.test('foo.bar')).toBe(true);
+      expect(re.test('fooXbar')).toBe(false);
+    });
+  });
+
+  describe('unifiedDiff', () => {
+    it('returns empty for identical text', () => {
+      expect(unifiedDiff('hello', 'hello')).toBe('');
+    });
+
+    it('shows added lines', () => {
+      const diff = unifiedDiff('a\nb', 'a\nb\nc');
+      expect(diff).toContain('+++');
+      expect(diff).toContain('@@');
+      expect(diff).toContain('+c');
+    });
+
+    it('shows removed lines', () => {
+      const diff = unifiedDiff('a\nb\nc', 'a\nb');
+      expect(diff).toContain('---');
+      expect(diff).toContain('-c');
+    });
+
+    it('includes file headers', () => {
+      const diff = unifiedDiff('a', 'b', { fromFile: 'old.txt', toFile: 'new.txt' });
+      expect(diff).toContain('--- old.txt');
+      expect(diff).toContain('+++ new.txt');
+    });
+  });
+
+  describe('stripAnsi', () => {
+    it('removes ANSI escape codes', () => {
+      const colored = '\x1b[31mred text\x1b[0m';
+      expect(stripAnsi(colored)).toBe('red text');
+    });
+
+    it('leaves plain text unchanged', () => {
+      expect(stripAnsi('plain text')).toBe('plain text');
+    });
+  });
+});
+
+function compileGglob_safe(pattern: string): RegExp {
+  return compileGlob(pattern);
+}

package/tests/image-resize.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import * as path from 'node:path';
+import { resizeImageBuffer } from '../src/utils/image-resize.js';
+import { PhotonImage } from '@silvia-odwyer/photon';
+
+const FIXTURE_DIR = path.join(__dirname, 'fixtures');
+const SMALL_PATH = path.join(FIXTURE_DIR, 'small-image.png');
+const LARGE_PATH = path.join(FIXTURE_DIR, 'large-image.png');
+
+beforeAll(() => {
+  mkdirSync(FIXTURE_DIR, { recursive: true });
+  try {
+    readFileSync(LARGE_PATH);
+  } catch {
+    const raw = new Uint8Array(200 * 150 * 4);
+    const img = new PhotonImage(raw, 200, 150);
+    writeFileSync(LARGE_PATH, Buffer.from(img.get_bytes()));
+    img.free();
+  }
+});
+
+describe('resizeImageBuffer', () => {
+  it('returns resized: false for small image', () => {
+    const buf = readFileSync(SMALL_PATH);
+    const result = resizeImageBuffer(buf, { maxWidth: 1568, maxHeight: 1568 });
+    expect(result.resized).toBe(false);
+    expect(result.buffer).toBe(buf);
+  });
+
+  it('returns resized: true for large image', () => {
+    const buf = readFileSync(LARGE_PATH);
+    const result = resizeImageBuffer(buf, { maxWidth: 100, maxHeight: 100 });
+    expect(result.resized).toBe(true);
+    expect(result.mediaType).toBe('image/jpeg');
+    expect(result.buffer.length).toBeLessThan(buf.length);
+  });
+
+  it('does not upscale small image', () => {
+    const buf = readFileSync(SMALL_PATH);
+    const result = resizeImageBuffer(buf, { maxWidth: 5000, maxHeight: 5000 });
+    expect(result.resized).toBe(false);
+  });
+
+  it('applies quality setting', () => {
+    const buf = readFileSync(LARGE_PATH);
+    const high = resizeImageBuffer(buf, { maxWidth: 100, maxHeight: 100, quality: 95 });
+    const low = resizeImageBuffer(buf, { maxWidth: 100, maxHeight: 100, quality: 10 });
+    expect(high.buffer.length).toBeGreaterThan(low.buffer.length);
+  });
+});

package/tests/output-serializer.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect } from 'vitest';
+import { createToolOutputSerializer } from '../src/execution/output-serializer.js';
+
+describe('OutputSerializer', () => {
+  const ser = createToolOutputSerializer();
+
+  it('serialize: string as-is', () => {
+    expect(ser.serialize('hello')).toBe('hello');
+  });
+
+  it('serialize: null/undefined to empty', () => {
+    expect(ser.serialize(null)).toBe('');
+    expect(ser.serialize(undefined)).toBe('');
+  });
+
+  it('serialize: number/boolean to string', () => {
+    expect(ser.serialize(42)).toBe('42');
+    expect(ser.serialize(true)).toBe('true');
+  });
+
+  it('serialize: array joined with newline', () => {
+    expect(ser.serialize(['a', 'b', 'c'])).toBe('a\nb\nc');
+  });
+
+  it('serialize: object with text field unwrapped', () => {
+    expect(ser.serialize({ text: 'hello' })).toBe('hello');
+  });
+
+  it('serialize: other object to JSON', () => {
+    const result = ser.serialize({ foo: 1, bar: 'baz' });
+    expect(JSON.parse(result)).toEqual({ foo: 1, bar: 'baz' });
+  });
+
+  it('enforceCap: under budget returns as-is', () => {
+    const { text, newBudget } = ser.enforceCap('hello', 1000);
+    expect(text).toBe('hello');
+    expect(newBudget).toBe(995);
+  });
+
+  it('enforceCap: over budget truncates with marker', () => {
+    const big = 'A'.repeat(5000);
+    const { text, newBudget } = ser.enforceCap(big, 1000);
+    expect(newBudget).toBe(0);
+    expect(text).toContain('[truncated');
+    expect(text).toContain('bytes]');
+    expect(text.length).toBeLessThan(big.length);
+    expect(text.startsWith('A')).toBe(true);
+  });
+
+  it('enforceCap: zero remaining produces marker only', () => {
+    const { text, newBudget } = ser.enforceCap('hello', 0);
+    expect(newBudget).toBe(0);
+    expect(text).toContain('[truncated');
+  });
+
+  it('truncateForEvent: short text unchanged', () => {
+    expect(ser.truncateForEvent('short')).toBe('short');
+  });
+
+  it('truncateForEvent: long text truncated', () => {
+    const long = 'A'.repeat(500);
+    const result = ser.truncateForEvent(long, 100);
+    expect(result.length).toBeLessThan(long.length);
+    expect(result).toContain('…');
+  });
+
+  it('truncateForEvent: default maxChars is 400', () => {
+    const long = 'A'.repeat(500);
+    const result = ser.truncateForEvent(long);
+    expect(result).toContain('…');
+  });
+
+  it('enforceCap: preserves head and tail', () => {
+    const text = 'HEAD' + 'X'.repeat(3000) + 'TAIL';
+    const { text: result } = ser.enforceCap(text, 200);
+    expect(result.startsWith('HEAD')).toBe(true);
+    expect(result.endsWith('TAIL')).toBe(true);
+  });
+});