ultraclaude-agent 0.0.23 → 0.0.25

package/__tests__/project-watcher.test.ts

@@ -0,0 +1,199 @@
+// Integration test — real chokidar against tmp project dir. Regression
+// guard for the project watcher's parent-directory watch pattern on
+// .git/HEAD and .claude/ultra/version.json.
+//
+// Per the Lead amendment (shared/lead.md § Amendments 2026-04-12):
+// these tests are regression guards, not failing-first reproductions.
+// chokidar 5.x on Linux auto-re-registers inodes in `_handleFile`, so a
+// simple multi-rename scenario passes against both unfixed and fixed code.
+// The tests exist to ensure the parent-dir + basename-filter pattern
+// correctly fires on atomic tmp+mv across multiple renames — verifying
+// the fix doesn't introduce a new breakage.
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, writeFile, rename, mkdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+// --- Mock ./sync.js — observable surface for the handlers ---
+
+const mockInitialSync = vi.fn();
+const mockPushVersionMetadata = vi.fn();
+const mockSyncFile = vi.fn();
+const mockDeleteFiles = vi.fn();
+const mockCreateSnapshot = vi.fn();
+const mockHideBranches = vi.fn();
+
+vi.mock('../src/sync.js', () => ({
+  syncFile: (...args: unknown[]) => mockSyncFile(...args),
+  deleteFiles: (...args: unknown[]) => mockDeleteFiles(...args),
+  initialSync: (...args: unknown[]) => mockInitialSync(...args),
+  createSnapshot: (...args: unknown[]) => mockCreateSnapshot(...args),
+  pushVersionMetadata: (...args: unknown[]) => mockPushVersionMetadata(...args),
+  hideBranches: (...args: unknown[]) => mockHideBranches(...args),
+}));
+
+// --- Mock logger ---
+
+vi.mock('../src/logger.js', () => ({
+  logger: {
+    child: () => ({
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn(),
+    }),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+  },
+}));
+
+describe('project watcher — atomic tmp+mv (real chokidar)', () => {
+  let tempDir: string;
+  let watcher: { close: () => Promise<void> } | null = null;
+
+  const testCredentials = {
+    apiKey: 'test-key',
+    userId: 'test-user',
+    serverUrl: 'http://localhost:3000',
+  };
+
+  beforeEach(async () => {
+    mockInitialSync.mockReset().mockResolvedValue(undefined);
+    mockPushVersionMetadata.mockReset().mockResolvedValue(undefined);
+    mockSyncFile.mockReset().mockResolvedValue(undefined);
+    mockDeleteFiles.mockReset().mockResolvedValue(undefined);
+    mockCreateSnapshot.mockReset().mockResolvedValue(true);
+    mockHideBranches.mockReset().mockResolvedValue(true);
+
+    tempDir = await mkdtemp(join(tmpdir(), 'project-watcher-test-'));
+
+    // Seed a minimal git repo layout
+    await mkdir(join(tempDir, '.git', 'refs', 'heads'), { recursive: true });
+    await writeFile(join(tempDir, '.git', 'HEAD'), 'ref: refs/heads/main\n');
+    await writeFile(
+      join(tempDir, '.git', 'refs', 'heads', 'main'),
+      '0000000000000000000000000000000000000000\n',
+    );
+
+    // Seed Ultra Claude layout
+    await mkdir(join(tempDir, '.claude', 'ultra'), { recursive: true });
+    await writeFile(
+      join(tempDir, '.claude', 'ultra', 'version.json'),
+      JSON.stringify({ version: '1.0.0' }),
+    );
+
+    // Seed documentation/ dir so docWatcher has something to watch
+    await mkdir(join(tempDir, 'documentation'), { recursive: true });
+
+    // Fresh module load per test
+    vi.resetModules();
+    const { startProjectWatcher } = await import('../src/watcher.js');
+    watcher = startProjectWatcher({
+      projectId: 'test-project',
+      projectPath: tempDir,
+      credentials: testCredentials,
+    });
+
+    // Give chokidar time to reach ready state
+    await new Promise((r) => setTimeout(r, 300));
+  });
+
+  afterEach(async () => {
+    if (watcher) await watcher.close();
+    watcher = null;
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  it('fires initialSync on repeated atomic tmp+mv of .git/HEAD (branch switch simulation)', async () => {
+    // Reproduction: repeated atomic tmp+mv of .git/HEAD (as `git checkout` does).
+    // On the unfixed single-file watch, the inode swap orphans chokidar's
+    // internal watch after the first rename; subsequent checkouts are silent.
+    const headPath = join(tempDir, '.git', 'HEAD');
+    await mkdir(join(tempDir, '.git', 'refs', 'heads'), { recursive: true });
+    await writeFile(
+      join(tempDir, '.git', 'refs', 'heads', 'feature'),
+      '1111111111111111111111111111111111111111\n',
+    );
+    await writeFile(
+      join(tempDir, '.git', 'refs', 'heads', 'develop'),
+      '2222222222222222222222222222222222222222\n',
+    );
+
+    const checkoutAtomic = async (branch: string, label: string) => {
+      const tmpPath = `${headPath}.${label}.tmp`;
+      await writeFile(tmpPath, `ref: refs/heads/${branch}\n`);
+      await rename(tmpPath, headPath);
+    };
+
+    await checkoutAtomic('feature', 'a');
+    await vi.waitFor(
+      () => {
+        expect(mockInitialSync).toHaveBeenCalledTimes(1);
+      },
+      { timeout: 4000, interval: 100 },
+    );
+
+    await new Promise((r) => setTimeout(r, 500));
+
+    await checkoutAtomic('develop', 'b');
+    await vi.waitFor(
+      () => {
+        expect(mockInitialSync).toHaveBeenCalledTimes(2);
+      },
+      { timeout: 4000, interval: 100 },
+    );
+
+    await new Promise((r) => setTimeout(r, 500));
+
+    await checkoutAtomic('main', 'c');
+    await vi.waitFor(
+      () => {
+        expect(mockInitialSync).toHaveBeenCalledTimes(3);
+      },
+      { timeout: 4000, interval: 100 },
+    );
+  });
+
+  it('fires pushVersionMetadata on repeated atomic tmp+mv of .claude/ultra/version.json', async () => {
+    // Reproduction: repeated atomic tmp+mv. The awaitWriteFinish setting
+    // means we need to space them past the stability threshold.
+    const versionPath = join(tempDir, '.claude', 'ultra', 'version.json');
+
+    const bumpAtomic = async (version: string, label: string) => {
+      const tmpPath = `${versionPath}.${label}.tmp`;
+      await writeFile(tmpPath, JSON.stringify({ version }));
+      await rename(tmpPath, versionPath);
+    };
+
+    await bumpAtomic('2.0.0', 'a');
+    await vi.waitFor(
+      () => {
+        expect(mockPushVersionMetadata).toHaveBeenCalledTimes(1);
+      },
+      { timeout: 4000, interval: 100 },
+    );
+
+    await new Promise((r) => setTimeout(r, 500));
+
+    await bumpAtomic('2.1.0', 'b');
+    await vi.waitFor(
+      () => {
+        expect(mockPushVersionMetadata).toHaveBeenCalledTimes(2);
+      },
+      { timeout: 4000, interval: 100 },
+    );
+
+    await new Promise((r) => setTimeout(r, 500));
+
+    await bumpAtomic('2.2.0', 'c');
+    await vi.waitFor(
+      () => {
+        expect(mockPushVersionMetadata).toHaveBeenCalledTimes(3);
+      },
+      { timeout: 4000, interval: 100 },
+    );
+  });
+});

package/__tests__/sync-resilience.test.ts

@@ -0,0 +1,307 @@
+/**
+ * Tests for sync resilience fixes:
+ *   Fix A — apiRequest() times out after 15s via AbortController
+ *   Fix C — flushQueue() retains unprocessed items after network error break
+ *   Fix D — initialSync() runs file syncs concurrently at limit 10
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { join } from 'node:path';
+import { mkdtemp, writeFile, mkdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+
+// Mock fetch globally
+const mockFetch = vi.fn();
+vi.stubGlobal('fetch', mockFetch);
+
+// Mock config module
+vi.mock('../src/config.js', () => ({
+  loadCredentials: vi.fn().mockResolvedValue({
+    apiKey: 'test-api-key',
+    userId: 'test-user',
+    serverUrl: 'http://localhost:3000',
+  }),
+  getServerUrl: vi.fn().mockReturnValue('http://localhost:3000'),
+  getProjectId: vi.fn().mockResolvedValue('test-project-id'),
+  writeProjectId: vi.fn().mockResolvedValue(undefined),
+  paths: {
+    claudeProjects: '/tmp/test-claude-projects',
+    projectIdFile: '.claude/ultra/project-id',
+    oldConfigDir: '/tmp/test-old-config',
+  },
+}));
+
+// Mock logger
+vi.mock('../src/logger.js', () => ({
+  logger: {
+    child: () => ({
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn(),
+    }),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+  },
+}));
+
+const testCreds = { apiKey: 'test-api-key', userId: 'test-user', serverUrl: 'http://localhost:3000' };
+
+// --- Fix A: apiRequest timeout ---
+
+describe('sync — apiRequest timeout (Fix A)', () => {
+  beforeEach(() => {
+    mockFetch.mockReset();
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('returns NETWORK_ERROR when fetch hangs past 15 seconds', async () => {
+    vi.resetModules();
+    const { apiRequest } = await import('../src/sync.js');
+
+    // fetch that hangs until aborted — simulates a stalled connection
+    mockFetch.mockImplementation((_url: string, options: RequestInit) => {
+      return new Promise((_resolve, reject) => {
+        if (options?.signal) {
+          options.signal.addEventListener('abort', () => {
+            reject(new DOMException('The operation was aborted', 'AbortError'));
+          });
+        }
+      });
+    });
+
+    const resultPromise = apiRequest('GET', '/api/test', undefined, testCreds);
+
+    // Advance past the 15s timeout
+    await vi.advanceTimersByTimeAsync(15_001);
+
+    const result = await resultPromise;
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error).toBe('NETWORK_ERROR');
+    }
+  });
+
+  it('succeeds when fetch resolves before timeout', async () => {
+    vi.resetModules();
+    const { apiRequest } = await import('../src/sync.js');
+
+    mockFetch.mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => ({ data: {} }),
+    });
+
+    const resultPromise = apiRequest('GET', '/api/test', undefined, testCreds);
+
+    // Advance a small amount (fetch resolves immediately with mock)
+    await vi.advanceTimersByTimeAsync(10);
+
+    const result = await resultPromise;
+    expect(result.success).toBe(true);
+  });
+
+  it('passes AbortController signal to fetch', async () => {
+    vi.resetModules();
+    const { apiRequest } = await import('../src/sync.js');
+
+    mockFetch.mockResolvedValue({ ok: true, status: 200 });
+
+    await apiRequest('POST', '/api/test', { data: 1 }, testCreds);
+
+    expect(mockFetch).toHaveBeenCalledOnce();
+    const fetchOptions = mockFetch.mock.calls[0]![1] as RequestInit;
+    expect(fetchOptions.signal).toBeInstanceOf(AbortSignal);
+  });
+});
+
+// --- Fix C: flushQueue retains unprocessed items ---
+
+describe('sync — flushQueue retains unprocessed items (Fix C)', () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    mockFetch.mockReset();
+    vi.useFakeTimers();
+    tempDir = await mkdtemp(join(tmpdir(), 'agent-flush-test-'));
+    await mkdir(join(tempDir, 'documentation'), { recursive: true });
+  });
+
+  afterEach(async () => {
+    vi.useRealTimers();
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  it('retains all unprocessed items after first network failure', async () => {
+    vi.resetModules();
+    const { syncMarkdownFile, getQueueSize, stopSync } = await import('../src/sync.js');
+
+    // Create 5 unique files and enqueue them all (all fail initially)
+    mockFetch.mockRejectedValue(new Error('Server down'));
+
+    const files: string[] = [];
+    for (let i = 0; i < 5; i++) {
+      const fp = join(tempDir, 'documentation', `file${i}.md`);
+      await writeFile(fp, `# Heading ${i}\n\nContent ${i}.`);
+      files.push(fp);
+      await syncMarkdownFile('test-project', tempDir, fp, testCreds, 'main');
+    }
+
+    expect(getQueueSize()).toBe(5);
+
+    // Server comes back but is flaky — first item succeeds, second fails with network error
+    let callCount = 0;
+    mockFetch.mockImplementation(() => {
+      callCount++;
+      if (callCount === 1) {
+        // First item succeeds
+        return Promise.resolve({
+          ok: true,
+          status: 200,
+          json: async () => ({ data: { upserted: 1 } }),
+        });
+      }
+      // Second item: network error — should break and retain remaining
+      return Promise.reject(new Error('Network error'));
+    });
+
+    // Trigger flush via retry timer
+    await vi.advanceTimersByTimeAsync(5_001);
+
+    // Item 1 succeeded, item 2 failed (retained), items 3-5 never attempted (retained)
+    // Total remaining = 4 (failed item + 3 unprocessed)
+    expect(getQueueSize()).toBe(4);
+
+    stopSync();
+  });
+
+  it('retains unprocessed items when first item fails', async () => {
+    vi.resetModules();
+    const { syncMarkdownFile, getQueueSize, stopSync } = await import('../src/sync.js');
+
+    // Enqueue 3 items (all fail initially)
+    mockFetch.mockRejectedValue(new Error('Server down'));
+
+    for (let i = 0; i < 3; i++) {
+      const fp = join(tempDir, 'documentation', `item${i}.md`);
+      await writeFile(fp, `# Item ${i}\n\nContent.`);
+      await syncMarkdownFile('test-project', tempDir, fp, testCreds, 'main');
+    }
+
+    expect(getQueueSize()).toBe(3);
+
+    // First flush attempt — first item fails immediately
+    mockFetch.mockRejectedValue(new Error('Still down'));
+
+    await vi.advanceTimersByTimeAsync(5_001);
+
+    // All 3 items should be retained (1 failed + 2 unprocessed)
+    expect(getQueueSize()).toBe(3);
+
+    stopSync();
+  });
+});
+
+// --- Fix D: initialSync concurrency ---
+
+describe('sync — initialSync concurrency (Fix D)', () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    mockFetch.mockReset();
+    tempDir = await mkdtemp(join(tmpdir(), 'agent-initial-sync-'));
+    await mkdir(join(tempDir, 'documentation'), { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  it('syncs files concurrently with p-limit at concurrency 10', async () => {
+    vi.resetModules();
+
+    // Create 15 markdown files to sync
+    for (let i = 0; i < 15; i++) {
+      const subdir = join(tempDir, 'documentation', `dir${i}`);
+      await mkdir(subdir, { recursive: true });
+      await writeFile(join(subdir, `file${i}.md`), `# File ${i}\n\nContent ${i}.`);
+    }
+
+    // Track concurrency: how many sync requests are in-flight at once
+    let activeCalls = 0;
+    let maxConcurrent = 0;
+
+    // Mock manifest fetch (first call)
+    mockFetch.mockImplementation(async (url: string) => {
+      if ((url as string).includes('/api/sync/manifest')) {
+        return { ok: true, json: async () => ({ data: { files: {} } }) };
+      }
+      if ((url as string).includes('/api/sync/reconcile')) {
+        return { ok: true, json: async () => ({ data: { prunedFiles: 0, prunedPlans: 0, prunedBacklogItems: 0 } }) };
+      }
+
+      // Sync requests — track concurrency
+      activeCalls++;
+      maxConcurrent = Math.max(maxConcurrent, activeCalls);
+
+      // Simulate some async work
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      activeCalls--;
+      return { ok: true, json: async () => ({ data: { upserted: 1 } }) };
+    });
+
+    const { initialSync } = await import('../src/sync.js');
+    await initialSync('test-project', tempDir, testCreds, 'main');
+
+    // Verify concurrency was bounded at 10
+    expect(maxConcurrent).toBeLessThanOrEqual(10);
+    // Verify multiple files were synced (some concurrently)
+    expect(maxConcurrent).toBeGreaterThan(1);
+
+    // Verify all files were synced — count sync POST calls (sections + reconcile)
+    const syncCalls = mockFetch.mock.calls.filter(
+      (call: unknown[]) => (call[0] as string).includes('/api/sync/sections'),
+    );
+    expect(syncCalls.length).toBe(15);
+  });
+
+  it('uses Promise.allSettled so one file failure does not abort others', async () => {
+    vi.resetModules();
+
+    // Create 3 files
+    for (let i = 0; i < 3; i++) {
+      await writeFile(join(tempDir, 'documentation', `f${i}.md`), `# F${i}\n\nContent.`);
+    }
+
+    let syncCallCount = 0;
+    mockFetch.mockImplementation(async (url: string) => {
+      if ((url as string).includes('/api/sync/manifest')) {
+        return { ok: true, json: async () => ({ data: { files: {} } }) };
+      }
+      if ((url as string).includes('/api/sync/reconcile')) {
+        return { ok: true, json: async () => ({ data: { prunedFiles: 0, prunedPlans: 0, prunedBacklogItems: 0 } }) };
+      }
+      syncCallCount++;
+      // Second sync call fails
+      if (syncCallCount === 2) {
+        return { ok: false, status: 500 };
+      }
+      return { ok: true, json: async () => ({ data: { upserted: 1 } }) };
+    });
+
+    const { initialSync } = await import('../src/sync.js');
+
+    // Should NOT throw — allSettled absorbs individual rejections
+    await expect(initialSync('test-project', tempDir, testCreds, 'main')).resolves.toBeUndefined();
+
+    // All 3 files should have been attempted despite the failure of the second
+    expect(syncCallCount).toBe(3);
+  });
+});