opencode-dux 1.0.0

package/src/utils/logger.test.ts

@@ -0,0 +1,220 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {
+  flushLoggerForTesting,
+  getLogDir,
+  initLogger,
+  log,
+  resetLogger,
+} from './logger';
+
+describe('logger', () => {
+  let tmpDir: string;
+  let origLogDir: string | undefined;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'logger-test-'));
+    origLogDir = process.env.OPENCODE_LOG_DIR;
+    process.env.OPENCODE_LOG_DIR = tmpDir;
+    resetLogger();
+  });
+
+  afterEach(async () => {
+    await flushLoggerForTesting();
+    if (origLogDir === undefined) {
+      delete process.env.OPENCODE_LOG_DIR;
+    } else {
+      process.env.OPENCODE_LOG_DIR = origLogDir;
+    }
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test('log() silently no-ops before initLogger()', () => {
+    log('should not crash');
+    expect(fs.readdirSync(tmpDir).length).toBe(0);
+  });
+
+  test('initLogger creates per-session log file', () => {
+    initLogger('20260416T143052');
+    log('test message');
+
+    const files = fs.readdirSync(tmpDir);
+    expect(files).toEqual(['opencode-dux.20260416T143052.log']);
+  });
+
+  test('writes log message with timestamp', async () => {
+    initLogger('session1');
+    log('timestamped message');
+    await flushLoggerForTesting();
+
+    const logPath = path.join(tmpDir, 'opencode-dux.session1.log');
+    const content = fs.readFileSync(logPath, 'utf-8');
+    expect(content).toMatch(/\[\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z\]/);
+    expect(content).toContain('timestamped message');
+  });
+
+  test('logs message with data object', async () => {
+    initLogger('session1');
+    log('message with data', { key: 'value', number: 42 });
+    await flushLoggerForTesting();
+
+    const logPath = path.join(tmpDir, 'opencode-dux.session1.log');
+    const content = fs.readFileSync(logPath, 'utf-8');
+    expect(content).toContain('"key":"value"');
+    expect(content).toContain('"number":42');
+  });
+
+  test('logs message without extra JSON when no data', async () => {
+    initLogger('session1');
+    log('message without data');
+    await flushLoggerForTesting();
+
+    const logPath = path.join(tmpDir, 'opencode-dux.session1.log');
+    const content = fs.readFileSync(logPath, 'utf-8');
+    expect(content.trim()).toMatch(/message without data\s*$/);
+  });
+
+  test('appends multiple log entries', async () => {
+    initLogger('session1');
+    log('first');
+    log('second');
+    log('third');
+    await flushLoggerForTesting();
+
+    const logPath = path.join(tmpDir, 'opencode-dux.session1.log');
+    const lines = fs.readFileSync(logPath, 'utf-8').trim().split('\n');
+    expect(lines.length).toBe(3);
+    expect(lines[0]).toContain('first');
+    expect(lines[1]).toContain('second');
+    expect(lines[2]).toContain('third');
+  });
+
+  test('initLogger called twice uses second session file', async () => {
+    initLogger('session1');
+    log('from session1');
+    initLogger('session2');
+    log('from session2');
+    await flushLoggerForTesting();
+
+    const files = fs.readdirSync(tmpDir).sort();
+    expect(files).toEqual([
+      'opencode-dux.session1.log',
+      'opencode-dux.session2.log',
+    ]);
+
+    const content1 = fs.readFileSync(path.join(tmpDir, files[0]), 'utf-8');
+    const content2 = fs.readFileSync(path.join(tmpDir, files[1]), 'utf-8');
+    expect(content1).toContain('from session1');
+    expect(content1).not.toContain('from session2');
+    expect(content2).toContain('from session2');
+  });
+
+  test('cleanup keeps only the latest 10 log files', () => {
+    const baseTime = Date.now() - 50_000;
+    for (let i = 0; i < 10; i++) {
+      const fileName = `opencode-dux.seed-${i}.log`;
+      const filePath = path.join(tmpDir, fileName);
+      fs.writeFileSync(filePath, `seed-${i}\n`);
+      const mtime = baseTime + i * 1_000;
+      fs.utimesSync(filePath, new Date(mtime), new Date(mtime));
+    }
+
+    initLogger('current');
+    log('init');
+
+    const files = fs
+      .readdirSync(tmpDir)
+      .filter(
+        (file) =>
+          file.startsWith('opencode-dux.') && file.endsWith('.log'),
+      )
+      .sort();
+
+    expect(files.length).toBe(10);
+    expect(files).toContain('opencode-dux.current.log');
+    expect(files).not.toContain('opencode-dux.seed-0.log');
+    expect(files).toContain('opencode-dux.seed-9.log');
+  });
+
+  test('cleanup does not delete current session log when overflowing', () => {
+    const baseTime = Date.now() - 100_000;
+    for (let i = 0; i < 25; i++) {
+      const fileName = `opencode-dux.old-${i}.log`;
+      const filePath = path.join(tmpDir, fileName);
+      fs.writeFileSync(filePath, `old-${i}\n`);
+      const mtime = baseTime + i * 1_000;
+      fs.utimesSync(filePath, new Date(mtime), new Date(mtime));
+    }
+
+    initLogger('current');
+
+    const files = fs
+      .readdirSync(tmpDir)
+      .filter(
+        (file) =>
+          file.startsWith('opencode-dux.') && file.endsWith('.log'),
+      );
+
+    expect(files.length).toBe(10);
+    expect(files).toContain('opencode-dux.current.log');
+  });
+
+  test('cleanup with no existing files does not crash', () => {
+    expect(() => initLogger('fresh')).not.toThrow();
+    log('init');
+    const files = fs.readdirSync(tmpDir);
+    expect(files.find((f) => f.includes('fresh'))).toBeDefined();
+  });
+
+  test('handles circular references in data', async () => {
+    initLogger('session1');
+    const circular: any = { name: 'test' };
+    circular.self = circular;
+
+    expect(() => log('circular data', circular)).not.toThrow();
+    await flushLoggerForTesting();
+
+    const logPath = path.join(tmpDir, 'opencode-dux.session1.log');
+    const content = fs.readFileSync(logPath, 'utf-8');
+    expect(content).toContain('circular data');
+    expect(content).toContain('[unserializable]');
+  });
+
+  test('getLogDir returns OPENCODE_LOG_DIR when set', () => {
+    expect(getLogDir()).toBe(tmpDir);
+  });
+
+  test('getLogDir falls back to os.homedir when env not set', () => {
+    delete process.env.OPENCODE_LOG_DIR;
+    try {
+      expect(getLogDir()).toBe(
+        path.join(os.homedir(), '.local/share/opencode'),
+      );
+    } finally {
+      if (origLogDir === undefined) {
+        delete process.env.OPENCODE_LOG_DIR;
+      } else {
+        process.env.OPENCODE_LOG_DIR = origLogDir;
+      }
+    }
+  });
+
+  test('handles complex data structures', async () => {
+    initLogger('session1');
+    log('complex data', {
+      nested: { deep: { value: 'test' } },
+      array: [1, 2, 3],
+      boolean: true,
+      null: null,
+    });
+    await flushLoggerForTesting();
+
+    const logPath = path.join(tmpDir, 'opencode-dux.session1.log');
+    const content = fs.readFileSync(logPath, 'utf-8');
+    expect(content).toContain('"nested":');
+    expect(content).toContain('"array":[1,2,3]');
+    expect(content).toContain('"boolean":true');
+  });
+});

package/src/utils/logger.ts

@@ -0,0 +1,136 @@
+import * as fs from 'node:fs';
+import { appendFile } from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+const LOG_PREFIX = 'opencode-dux.';
+const LOG_SUFFIX = '.log';
+const MAX_LOG_FILES = 10;
+const MAX_BG_TASK_FILES = 10;
+
+let logFile: string | null = null;
+let writeChain: Promise<void> = Promise.resolve();
+
+function getLogDir(): string {
+  return (
+    process.env.OPENCODE_LOG_DIR ??
+    path.join(os.homedir(), '.local/share/opencode')
+  );
+}
+
+function trimByCount(
+  filePaths: string[],
+  maxFiles: number,
+  preservePath?: string,
+): void {
+  if (filePaths.length <= maxFiles) return;
+
+  const sortedByMtime = filePaths
+    .map((filePath) => {
+      try {
+        return { filePath, mtimeMs: fs.statSync(filePath).mtimeMs };
+      } catch {
+        return null;
+      }
+    })
+    .filter((entry): entry is { filePath: string; mtimeMs: number } =>
+      Boolean(entry),
+    )
+    .sort((a, b) => a.mtimeMs - b.mtimeMs);
+
+  const overflow = sortedByMtime.length - maxFiles;
+  if (overflow <= 0) return;
+
+  const candidates = preservePath
+    ? sortedByMtime.filter((entry) => entry.filePath !== preservePath)
+    : sortedByMtime;
+
+  for (const entry of candidates.slice(0, overflow)) {
+    try {
+      fs.unlinkSync(entry.filePath);
+    } catch {
+      // Skip individual file errors
+    }
+  }
+}
+
+function cleanupOldLogs(logDir: string, preservePath?: string): void {
+  try {
+    const entries = fs.readdirSync(logDir);
+    const logFiles = entries
+      .filter(
+        (entry) => entry.startsWith(LOG_PREFIX) && entry.endsWith(LOG_SUFFIX),
+      )
+      .map((entry) => path.join(logDir, entry));
+
+    trimByCount(logFiles, MAX_LOG_FILES, preservePath);
+  } catch {
+    // Directory may not exist yet - that's fine
+  }
+
+  // Apply the same count-based retention to persisted background task files
+  try {
+    const bgTaskDir = path.join(logDir, 'bg-tasks');
+    const taskFiles = fs
+      .readdirSync(bgTaskDir)
+      .filter((entry) => entry.endsWith('.json'))
+      .map((entry) => path.join(bgTaskDir, entry));
+
+    trimByCount(taskFiles, MAX_BG_TASK_FILES);
+  } catch {
+    // bg-tasks dir may not exist yet - that's fine
+  }
+}
+
+export function initLogger(sessionId: string): void {
+  const dir = getLogDir();
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch {
+    // Directory creation failed - logging will silently fail
+  }
+  logFile = path.join(dir, `${LOG_PREFIX}${sessionId}${LOG_SUFFIX}`);
+  try {
+    fs.closeSync(fs.openSync(logFile, 'a'));
+  } catch {
+    // File creation failed - later writes will silently fail
+  }
+  cleanupOldLogs(dir, logFile);
+}
+
+/** @internal Reset logger state for testing */
+export function resetLogger(): void {
+  logFile = null;
+  writeChain = Promise.resolve();
+}
+
+/** @internal Wait for queued log writes in tests. */
+export async function flushLoggerForTesting(): Promise<void> {
+  await writeChain;
+}
+
+export { getLogDir };
+
+export function log(message: string, data?: unknown): void {
+  const target = logFile;
+  if (!target) return; // Uninitialized - silently no-op
+  try {
+    const timestamp = new Date().toISOString();
+    let dataStr = '';
+    if (data !== undefined) {
+      try {
+        dataStr = JSON.stringify(data);
+      } catch {
+        dataStr = '[unserializable]';
+      }
+    }
+    const logEntry = `[${timestamp}] ${message} ${dataStr}\n`;
+    writeChain = writeChain
+      .then(() => appendFile(target, logEntry))
+      .catch(() => {
+        // Silently ignore logging errors and keep future writes alive
+      });
+  } catch {
+    // Silently ignore logging errors
+  }
+}

package/src/utils/polling.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, test } from 'bun:test';
+import { delay, pollUntilStable } from './polling';
+
+describe('pollUntilStable', () => {
+  test('returns success when condition becomes stable', async () => {
+    let callCount = 0;
+    const fetchFn = async () => {
+      callCount++;
+      return callCount >= 3 ? 'stable' : 'changing';
+    };
+
+    const isStable = (current: string, previous: string | null) => {
+      return current === 'stable' && previous === 'stable';
+    };
+
+    const result = await pollUntilStable(fetchFn, isStable, {
+      pollInterval: 10,
+      maxPollTime: 1000,
+      stableThreshold: 2,
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.data).toBe('stable');
+    expect(result.timedOut).toBeUndefined();
+    expect(result.aborted).toBeUndefined();
+  });
+
+  test('returns timeout when max poll time exceeded', async () => {
+    const fetchFn = async () => 'always-changing';
+    const isStable = () => false; // Never stable
+
+    const result = await pollUntilStable(fetchFn, isStable, {
+      pollInterval: 10,
+      maxPollTime: 50, // Very short timeout
+      stableThreshold: 2,
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.timedOut).toBe(true);
+    expect(result.data).toBe('always-changing');
+  });
+
+  test('returns aborted when signal is aborted', async () => {
+    const controller = new AbortController();
+    const fetchFn = async () => {
+      // Abort after first call
+      controller.abort();
+      return 'data';
+    };
+
+    const isStable = () => false;
+
+    const result = await pollUntilStable(fetchFn, isStable, {
+      pollInterval: 10,
+      maxPollTime: 1000,
+      signal: controller.signal,
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.aborted).toBe(true);
+  });
+
+  test('respects custom stability threshold', async () => {
+    let callCount = 0;
+    const fetchFn = async () => {
+      callCount++;
+      return callCount >= 2 ? 'stable' : 'changing';
+    };
+
+    const isStable = (
+      current: string,
+      previous: string | null,
+      _stableCount: number,
+    ) => {
+      return current === 'stable' && previous === 'stable';
+    };
+
+    const result = await pollUntilStable(fetchFn, isStable, {
+      pollInterval: 10,
+      maxPollTime: 1000,
+      stableThreshold: 3, // Require 3 stable polls
+    });
+
+    expect(result.success).toBe(true);
+    expect(callCount).toBeGreaterThanOrEqual(5); // At least 2 changing + 3 stable
+  });
+
+  test('resets stable count when condition becomes unstable', async () => {
+    let callCount = 0;
+    const values = ['a', 'a', 'b', 'b', 'b', 'b']; // Unstable, then stable
+    const fetchFn = async () => values[callCount++] || 'b';
+
+    const isStable = (current: string, previous: string | null) => {
+      return current === previous && current === 'b';
+    };
+
+    const result = await pollUntilStable(fetchFn, isStable, {
+      pollInterval: 10,
+      maxPollTime: 1000,
+      stableThreshold: 3,
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.data).toBe('b');
+  });
+
+  test('uses default options when not provided', async () => {
+    let callCount = 0;
+    const fetchFn = async () => {
+      callCount++;
+      return callCount >= 2 ? 'stable' : 'changing';
+    };
+
+    const isStable = (current: string, previous: string | null) => {
+      return current === 'stable' && previous === 'stable';
+    };
+
+    const result = await pollUntilStable(fetchFn, isStable);
+
+    expect(result.success).toBe(true);
+    expect(result.data).toBe('stable');
+  });
+
+  test('handles fetchFn that throws errors', async () => {
+    const fetchFn = async () => {
+      throw new Error('Fetch failed');
+    };
+
+    const isStable = () => false;
+
+    await expect(
+      pollUntilStable(fetchFn, isStable, {
+        pollInterval: 10,
+        maxPollTime: 100,
+      }),
+    ).rejects.toThrow('Fetch failed');
+  });
+
+  test('passes stable count to isStable function', async () => {
+    let _callCount = 0;
+    const fetchFn = async () => {
+      _callCount++;
+      return 'data';
+    };
+
+    let maxStableCount = 0;
+    const isStable = (
+      current: string,
+      previous: string | null,
+      stableCount: number,
+    ) => {
+      maxStableCount = Math.max(maxStableCount, stableCount);
+      // Check if data is actually stable (same as previous)
+      return current === previous && current === 'data';
+    };
+
+    const result = await pollUntilStable(fetchFn, isStable, {
+      pollInterval: 10,
+      maxPollTime: 1000,
+      stableThreshold: 3,
+    });
+
+    expect(result.success).toBe(true);
+    expect(maxStableCount).toBeGreaterThanOrEqual(2);
+  });
+});
+
+describe('delay', () => {
+  test('delays for specified milliseconds', async () => {
+    const start = Date.now();
+    await delay(50);
+    const elapsed = Date.now() - start;
+
+    // Allow some tolerance for timing
+    expect(elapsed).toBeGreaterThanOrEqual(45);
+    expect(elapsed).toBeLessThan(100);
+  });
+
+  test('resolves without value', async () => {
+    const result = await delay(10);
+    expect(result).toBeUndefined();
+  });
+
+  test('can be used in promise chains', async () => {
+    const result = await Promise.resolve('test')
+      .then((val) => delay(10).then(() => val))
+      .then((val) => val.toUpperCase());
+
+    expect(result).toBe('TEST');
+  });
+});

package/src/utils/polling.ts

@@ -0,0 +1,67 @@
+import {
+  MAX_POLL_TIME_MS,
+  POLL_INTERVAL_MS,
+  STABLE_POLLS_THRESHOLD,
+} from '../config';
+
+export interface PollOptions {
+  pollInterval?: number;
+  maxPollTime?: number;
+  stableThreshold?: number;
+  signal?: AbortSignal;
+}
+
+export interface PollResult<T> {
+  success: boolean;
+  data?: T;
+  timedOut?: boolean;
+  aborted?: boolean;
+}
+
+/**
+ * Generic polling utility that waits for a condition to be met.
+ * Returns when the condition is satisfied or timeout/abort occurs.
+ */
+export async function pollUntilStable<T>(
+  fetchFn: () => Promise<T>,
+  isStable: (current: T, previous: T | null, stableCount: number) => boolean,
+  opts: PollOptions = {},
+): Promise<PollResult<T>> {
+  const pollInterval = opts.pollInterval ?? POLL_INTERVAL_MS;
+  const maxPollTime = opts.maxPollTime ?? MAX_POLL_TIME_MS;
+  const stableThreshold = opts.stableThreshold ?? STABLE_POLLS_THRESHOLD;
+
+  const pollStart = Date.now();
+  let previousData: T | null = null;
+  let stablePolls = 0;
+
+  while (Date.now() - pollStart < maxPollTime) {
+    if (opts.signal?.aborted) {
+      return { success: false, aborted: true };
+    }
+
+    await new Promise((r) => setTimeout(r, pollInterval));
+
+    const currentData = await fetchFn();
+
+    if (isStable(currentData, previousData, stablePolls)) {
+      stablePolls++;
+      if (stablePolls >= stableThreshold) {
+        return { success: true, data: currentData };
+      }
+    } else {
+      stablePolls = 0;
+    }
+
+    previousData = currentData;
+  }
+
+  return { success: false, timedOut: true, data: previousData ?? undefined };
+}
+
+/**
+ * Simple delay utility
+ */
+export function delay(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}