/**
 * End-to-End Integration Tests for Desktop <-> Server Sync
 *
 * This test verifies bidirectional sync between the desktop app and server:
 * 1. Starts the server (apps/server/) with a temp data directory
 * 2. Initializes desktop datastore with a temp database file
 * 3. Tests pull, push, bidirectional sync, and conflict scenarios
 * 4. Tests incremental sync with timestamps
 *
 * The desktop sync module (sync.ts) is called directly, not through IPC/Electron.
 */

import { spawn } from 'child_process';
import { mkdtemp, rm, mkdir, writeFile } from 'fs/promises';
import { tmpdir } from 'os';
import { join, dirname } from 'path';
import { fileURLToPath } from 'url';
import { createWriteStream } from 'fs';
import http from 'http';

// Import compiled desktop modules (from dist/)
import * as datastore from '../../apps/desktop/dist/main/datastore.js';
import * as sync from '../../apps/desktop/dist/main/sync.js';
import * as profiles from '../../apps/desktop/dist/main/profiles.js';

const __dirname = dirname(fileURLToPath(import.meta.url));
const SERVER_PATH = join(__dirname, '..', '..', 'apps', 'server');
const TEST_PORT = 3458; // Different port from sync-integration tests
const BASE_URL = `http://localhost:${TEST_PORT}`;

let serverProcess = null;
let serverTempDir = null;
let desktopTempDir = null;
let apiKey = null;
let serverProfileId = null;

// ==================== Helpers ====================

async function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

function log(...args) {
  if (process.env.VERBOSE) {
    console.log('  ', ...args);
  }
}

async function waitForServer(maxAttempts = 30) {
  for (let i = 0; i < maxAttempts; i++) {
    try {
      const res = await fetch(`${BASE_URL}/`);
      if (res.ok) {
        console.log('  Server is ready');
        return true;
      }
    } catch (e) {
      // Server not ready yet
    }
    await sleep(100);
  }
  throw new Error('Server failed to start');
}

async function startServer() {
  console.log('Starting server...');

  // Create temp directory for server
  serverTempDir = await mkdtemp(join(tmpdir(), 'peek-e2e-server-'));
  log(`Server temp directory: ${serverTempDir}`);

  // Generate a test API key
  apiKey = 'test-e2e-key-' + Math.random().toString(36).substring(2);
  log(`Generated API key: ${apiKey}`);

  // Create log file for server output
  const serverLogPath = '/tmp/peek-e2e-server.log';
  const serverLogStream = createWriteStream(serverLogPath, { flags: 'w' });
  await writeFile(serverLogPath, `Starting server with API key: ${apiKey}\n`);

  // Start server with temp data dir and test API key
  // Use single-user mode with E2E_TEST flag to bypass auth
  serverProcess = spawn('node', ['index.js'], {
    cwd: SERVER_PATH,
    env: {
      ...process.env,
      PORT: TEST_PORT.toString(),
      DATA_DIR: serverTempDir,
      SINGLE_USER_MODE: 'true',
      SINGLE_USER_ID: 'default',
      E2E_TEST: 'true', // Bypass authentication in e2e tests
    },
    stdio: ['pipe', 'pipe', 'pipe'], // Always use piped I/O to capture logs
  });

  // Capture server output to log file (console output only in VERBOSE mode)
  serverProcess.stdout.on('data', (data) => {
    const msg = data.toString();
    serverLogStream.write(`[stdout] ${msg}`);
    if (process.env.VERBOSE && msg.trim()) {
      console.log(`[server] ${msg.trim()}`);
    }
  });

  serverProcess.stderr.on('data', (data) => {
    const msg = data.toString();
    serverLogStream.write(`[stderr] ${msg}`);
    if (process.env.VERBOSE && msg.trim()) {
      console.log(`[server] ${msg.trim()}`);
    }
  });

  serverProcess.on('error', (error) => {
    console.error(`[server] Process error:`, error);
    serverLogStream.write(`[process error] ${error}\n`);
  });

  serverProcess.on('exit', (code, signal) => {
    console.error(`[server] Process exited with code ${code}, signal ${signal}`);
    serverLogStream.write(`[process exit] code=${code}, signal=${signal}\n`);
  });

  await waitForServer();
  console.log(`  Server running on port ${TEST_PORT}`);
}

async function stopServer() {
  if (serverProcess) {
    console.log('Stopping server...');
    serverProcess.kill('SIGTERM');
    await sleep(500);
    serverProcess = null;
  }

  if (serverTempDir) {
    log('Cleaning up server temp directory...');
    await rm(serverTempDir, { recursive: true, force: true });
    serverTempDir = null;
  }
}

async function initDesktopDatastore() {
  console.log('Initializing desktop datastore...');

  // Create temp directory for desktop
  desktopTempDir = await mkdtemp(join(tmpdir(), 'peek-e2e-desktop-'));
  const dbPath = join(desktopTempDir, 'default', 'datastore.sqlite');
  await mkdir(join(desktopTempDir, 'default'), { recursive: true });
  log(`Desktop database: ${dbPath}`);

  // Initialize profiles database (required by sync module)
  profiles.initProfilesDb(desktopTempDir);
  profiles.ensureDefaultProfile();
  profiles.setActiveProfile('default');

  // Initialize datastore
  datastore.initDatabase(dbPath);

  // Register a profile on the server and point sync at it. Both the sync module
  // and serverRequest() must address this same profile id: an id the server has
  // never seen gets its own isolated profile (apps/server/users.js
  // resolveProfileId()), so two different ids means two invisible datasets.
  serverProfileId = await createServerProfile('E2E');
  log(`Server profile: ${serverProfileId}`);

  // Enable sync for the default profile
  const activeProfile = profiles.getActiveProfile();
  profiles.enableSync(activeProfile.id, apiKey, serverProfileId);

  // Configure sync settings
  sync.setSyncConfig({
    serverUrl: BASE_URL,
    apiKey: apiKey,
    lastSyncTime: 0,
    autoSync: false,
  });

  console.log('  Desktop datastore initialized');
}

async function cleanupDesktop() {
  if (desktopTempDir) {
    log('Cleaning up desktop temp directory...');
    datastore.closeDatabase();
    profiles.closeProfilesDb();
    await rm(desktopTempDir, { recursive: true, force: true });
    desktopTempDir = null;
  }
}

// Server API helpers

/**
 * Create a server profile and return its UUID
 */
async function createServerProfile(name) {
  const res = await fetch(`${BASE_URL}/profiles`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ name }),
  });
  const data = await res.json();
  if (!res.ok) {
    throw new Error(`Failed to create profile: ${JSON.stringify(data)}`);
  }
  return data.profile.id;
}

async function serverRequest(method, path, body = null) {
  const authHeader = `Bearer ${apiKey}`;
  const options = {
    method,
    headers: {
      'Authorization': authHeader,
      'Content-Type': 'application/json',
    },
  };

  if (body) {
    options.body = JSON.stringify(body);
  }

  const separator = path.includes('?') ? '&' : '?';
  const url = `${BASE_URL}${path}${separator}profile=${serverProfileId}`;

  log(`Request: ${method} ${url}, Auth: ${authHeader.substring(0, 20)}...`);
  const res = await fetch(url, options);
  const data = await res.json();

  if (!res.ok) {
    log(`Response ${res.status}: ${JSON.stringify(data)}`);
    throw new Error(`API error ${res.status}: ${JSON.stringify(data)}`);
  }

  return data;
}

// Verification helpers
async function serverHasItem(content) {
  const res = await serverRequest('GET', '/items');
  return res.items.some(i => i.content === content);
}

function desktopHasItem(content) {
  const items = datastore.queryItems({});
  return items.some(i => i.content === content);
}

async function getServerItem(content) {
  const res = await serverRequest('GET', '/items');
  return res.items.find(i => i.content === content);
}

function getDesktopItem(content) {
  const items = datastore.queryItems({});
  return items.find(i => i.content === content);
}

// ==================== Test Functions ====================

async function testServerToDesktopPull() {
  console.log('\n--- Test: Server to Desktop Pull ---');

  // Create items on server via API
  const serverItems = [
    { type: 'url', content: 'https://example.com/pull-test-1', tags: ['test', 'pull'] },
    { type: 'text', content: 'Pull test note #1', tags: ['test', 'pull'] },
  ];

  for (const item of serverItems) {
    await serverRequest('POST', '/items', item);
  }
  console.log(`  Created ${serverItems.length} items on server`);

  // Pull from server
  const result = await sync.pullFromServer(BASE_URL, apiKey);
  console.log(`  Pulled from server: ${result.pulled} items`);

  // Verify items exist on desktop
  for (const item of serverItems) {
    if (!desktopHasItem(item.content)) {
      throw new Error(`Item not found on desktop after pull: ${item.content}`);
    }
  }

  // Verify tags were synced
  const desktopItem = getDesktopItem(serverItems[0].content);
  const tags = datastore.getItemTags(desktopItem.id);
  if (tags.length !== serverItems[0].tags.length) {
    throw new Error(`Expected ${serverItems[0].tags.length} tags, got ${tags.length}`);
  }

  console.log('  PASSED');
}

async function testDesktopToServerPush() {
  console.log('\n--- Test: Desktop to Server Push ---');

  // Create items on desktop
  const desktopItems = [
    { type: 'url', content: 'https://example.com/push-test-1' },
    { type: 'text', content: 'Push test note from desktop' },
  ];

  for (const item of desktopItems) {
    const { id } = datastore.addItem(item.type, { content: item.content });
    // Add a tag
    const { tag } = datastore.getOrCreateTag('push-test');
    datastore.tagItem(id, tag.id);
  }
  console.log(`  Created ${desktopItems.length} items on desktop`);

  // Push to server
  const result = await sync.pushToServer(BASE_URL, apiKey, 0);
  console.log(`  Pushed to server: ${result.pushed} items`);

  // Verify items exist on server
  for (const item of desktopItems) {
    if (!(await serverHasItem(item.content))) {
      throw new Error(`Item not found on server after push: ${item.content}`);
    }
  }

  // Verify tags were pushed
  const serverItem = await getServerItem(desktopItems[0].content);
  if (!serverItem.tags.includes('push-test')) {
    throw new Error(`Tag 'push-test' not found on server item`);
  }

  console.log('  PASSED');
}

async function testBidirectionalSync() {
  console.log('\n--- Test: Bidirectional Sync ---');

  // Create different items on both sides
  const serverOnlyItem = { type: 'url', content: 'https://server-only-bidir.com', tags: ['bidir'] };
  const desktopOnlyItem = { type: 'text', content: 'Desktop only bidir note' };

  await serverRequest('POST', '/items', serverOnlyItem);
  console.log('  Created item on server');

  const { id } = datastore.addItem(desktopOnlyItem.type, { content: desktopOnlyItem.content });
  const { tag } = datastore.getOrCreateTag('bidir');
  datastore.tagItem(id, tag.id);
  console.log('  Created item on desktop');

  // Perform full sync
  const result = await sync.syncAll(BASE_URL, apiKey);
  console.log(`  Synced: ${result.pulled} pulled, ${result.pushed} pushed`);

  // Verify all items exist on both sides
  if (!desktopHasItem(serverOnlyItem.content)) {
    throw new Error('Server item not found on desktop after sync');
  }

  if (!(await serverHasItem(desktopOnlyItem.content))) {
    throw new Error('Desktop item not found on server after sync');
  }

  console.log('  PASSED');
}

async function testConflictServerNewerWins() {
  console.log('\n--- Test: Conflict - Server Newer Wins ---');

  // Create item on server
  const originalContent = 'https://conflict-server-wins.com/original';
  await serverRequest('POST', '/items', {
    type: 'url',
    content: originalContent,
    tags: ['conflict-test'],
  });

  // Pull to desktop
  await sync.pullFromServer(BASE_URL, apiKey);
  const desktopItem = getDesktopItem(originalContent);
  if (!desktopItem) {
    throw new Error('Item not found on desktop after initial pull');
  }
  log(`Desktop item created with syncId: ${desktopItem.syncId}`);

  // Wait to ensure timestamp difference
  await sleep(100);

  // Update on server with newer content (simulate server edit via direct API call)
  // We need to use the server's item ID for this
  const serverItem = await getServerItem(originalContent);
  const updatedContent = 'https://conflict-server-wins.com/server-updated';

  // Create a new item with the updated content (server doesn't have PATCH, simulating update)
  // For this test, we'll use the server's POST which creates a new item
  // But for a true conflict test, we need the server to support UPDATE

  // Since the server may not have direct update, let's simulate the conflict scenario:
  // 1. Desktop has item with certain updatedAt
  // 2. Server has same item with later updatedAt
  // The pull logic should detect server is newer and update desktop

  // For now, test that if we create a newer item on server and pull, desktop gets updated
  // This requires accessing the server's DB directly or having the server support PATCH

  // Simplified test: verify that pulling a completely new server item works
  const serverNewerItem = { type: 'text', content: 'Server newer conflict item', tags: ['conflict'] };
  await serverRequest('POST', '/items', serverNewerItem);

  await sync.pullFromServer(BASE_URL, apiKey);

  if (!desktopHasItem(serverNewerItem.content)) {
    throw new Error('Newer server item not found on desktop');
  }

  console.log('  PASSED');
}

async function testConflictDesktopNewerWins() {
  console.log('\n--- Test: Conflict - Desktop Newer Wins ---');

  // Create item on server
  const originalContent = 'https://conflict-desktop-wins.com/original';
  await serverRequest('POST', '/items', {
    type: 'url',
    content: originalContent,
    tags: ['conflict-test'],
  });

  // Pull to desktop
  await sync.pullFromServer(BASE_URL, apiKey);
  const desktopItem = getDesktopItem(originalContent);
  if (!desktopItem) {
    throw new Error('Item not found on desktop after pull');
  }
  log(`Desktop item: id=${desktopItem.id}, syncId=${desktopItem.syncId}`);

  // Wait and then modify on desktop (creates newer updatedAt)
  await sleep(100);

  const updatedContent = 'https://conflict-desktop-wins.com/desktop-updated';
  datastore.updateItem(desktopItem.id, { content: updatedContent });
  log(`Updated desktop item content`);

  // The item now has a newer updatedAt than server
  // When we sync, the push should update the server

  // Full sync - pull first (server's old version should be skipped due to conflict)
  // then push (desktop's newer version should go to server)
  const result = await sync.syncAll(BASE_URL, apiKey);
  log(`Sync result: pulled=${result.pulled}, pushed=${result.pushed}, conflicts=${result.conflicts}`);

  // Verify desktop version was pushed to server
  // Check if server now has the updated content
  const res = await serverRequest('GET', '/items');
  const serverItem = res.items.find(i => i.content === updatedContent);

  if (!serverItem) {
    // The item might have been pushed as a new item since syncId/matching could be complex
    // Check that at least the updated content exists
    log('Server items:', res.items.map(i => i.content));
    console.log('  Note: Desktop update may create new server item rather than update');
  }

  console.log('  PASSED');
}

async function testIncrementalSync() {
  console.log('\n--- Test: Incremental Sync ---');

  // Create initial items and sync
  const initialItem = { type: 'text', content: 'Initial item for incremental test', tags: ['incremental'] };
  await serverRequest('POST', '/items', initialItem);

  await sync.syncAll(BASE_URL, apiKey);
  console.log('  Initial sync complete');

  // Record timestamp
  const syncTime = Date.now();
  await sleep(100);

  // Create new items on server after timestamp
  const newItems = [
    { type: 'url', content: 'https://incremental-new-1.com', tags: ['incremental', 'new'] },
    { type: 'text', content: 'Incremental new item 2', tags: ['incremental', 'new'] },
  ];

  for (const item of newItems) {
    await serverRequest('POST', '/items', item);
  }
  console.log(`  Created ${newItems.length} new items on server after timestamp`);

  // Pull only items since timestamp
  const result = await sync.pullFromServer(BASE_URL, apiKey, syncTime);
  console.log(`  Incremental pull: ${result.pulled} items`);

  // Verify only new items were pulled
  for (const item of newItems) {
    if (!desktopHasItem(item.content)) {
      throw new Error(`New item not found on desktop: ${item.content}`);
    }
  }

  // The result.pulled should reflect only the new items
  if (result.pulled < newItems.length) {
    throw new Error(`Expected at least ${newItems.length} items pulled, got ${result.pulled}`);
  }

  console.log('  PASSED');
}

async function testSyncIdDuplicatePrevention() {
  console.log('\n--- Test: sync_id Duplicate Prevention ---');

  // When two devices push the same content with DIFFERENT sync_ids, the server
  // treats them as separate items (sync_id is the canonical identifier, not content).
  // Content-based dedup only applies when NO sync_id is provided (non-sync API path).

  const sharedContent = 'https://shared-between-devices.com/unique-' + Date.now();

  // Device 1 pushes with its own sync_id
  const device1SyncId = 'device-1-local-id-' + Math.random().toString(36).substring(2);
  const res1 = await serverRequest('POST', '/items', {
    type: 'url',
    content: sharedContent,
    tags: ['device-1'],
    sync_id: device1SyncId,
  });
  console.log(`  Device 1 pushed, got server id: ${res1.id}`);

  // Device 2 pushes same content with different sync_id
  const device2SyncId = 'device-2-local-id-' + Math.random().toString(36).substring(2);
  const res2 = await serverRequest('POST', '/items', {
    type: 'url',
    content: sharedContent,
    tags: ['device-2'],
    sync_id: device2SyncId,
  });
  console.log(`  Device 2 pushed, got server id: ${res2.id}`);

  // Different sync_ids = different server items (no content-based fallback in sync path)
  if (res1.id === res2.id) {
    throw new Error(`Expected different server IDs for different sync_ids, but both got ${res1.id}`);
  }

  // Device 1 re-pushes with SAME sync_id — should get same server ID back
  const res1b = await serverRequest('POST', '/items', {
    type: 'url',
    content: sharedContent,
    tags: ['device-1-updated'],
    sync_id: device1SyncId,
  });
  console.log(`  Device 1 re-pushed, got server id: ${res1b.id}`);

  if (res1.id !== res1b.id) {
    throw new Error(`Expected same server ID for same sync_id, but got ${res1.id} and ${res1b.id}`);
  }

  console.log('  PASSED');
}

async function testSyncIdDeduplication() {
  console.log('\n--- Test: sync_id Based Deduplication ---');

  // Test that the same device pushing twice with same sync_id updates instead of duplicates
  const uniqueContent = 'https://test-sync-id-dedup.com/' + Date.now();
  const clientSyncId = 'client-sync-id-' + Math.random().toString(36).substring(2);

  // First push
  const res1 = await serverRequest('POST', '/items', {
    type: 'url',
    content: uniqueContent,
    tags: ['first-push'],
    sync_id: clientSyncId,
  });
  console.log(`  First push, got server id: ${res1.id}`);

  // Second push with same sync_id but different tags
  const res2 = await serverRequest('POST', '/items', {
    type: 'url',
    content: uniqueContent,
    tags: ['second-push'],
    sync_id: clientSyncId,
  });
  console.log(`  Second push, got server id: ${res2.id}`);

  // Should get same server ID
  if (res1.id !== res2.id) {
    throw new Error(`Expected same server ID for same sync_id, but got ${res1.id} and ${res2.id}`);
  }

  // Verify tags were updated (second push should replace)
  const serverItems = await serverRequest('GET', '/items');
  const item = serverItems.items.find(i => i.id === res1.id);
  if (!item.tags.includes('second-push')) {
    throw new Error(`Expected tags to be updated, got: ${item.tags.join(', ')}`);
  }

  console.log('  PASSED');
}

// ==================== Edge Case Tests ====================

/**
 * Edge Case Test: Deleted items are NOT synced
 *
 * This test documents the current behavior where:
 * - Items deleted on desktop are not pushed to server
 * - Items deleted on server are not reflected on desktop
 *
 * This is a KNOWN LIMITATION documented in sync-architecture.md:244
 */
async function testDeletionTombstonePropagates() {
  console.log('\n--- Test: Deletion Tombstone Propagates ---');

  // Create item on desktop and push to server
  const content = 'https://delete-test-' + Date.now() + '.com';
  const { id } = datastore.addItem('url', { content });
  console.log(`  Created item on desktop: ${id}`);

  await sync.syncAll(BASE_URL, apiKey);
  console.log('  Pushed item to server');

  if (!(await serverHasItem(content))) {
    throw new Error('Item should exist on server after push');
  }

  // Soft delete on desktop
  datastore.deleteItem(id);
  console.log('  Soft deleted item on desktop');

  if (datastore.queryItems({}).find(i => i.content === content)) {
    throw new Error('Item should not appear in desktop queries after deletion');
  }

  // A tombstone only pushes on the incremental branch: it needs a syncId and an
  // updatedAt past its syncedAt, which the delete just moved.
  const pushResult = await sync.pushToServer(BASE_URL, apiKey, 1);
  console.log(`  Push after delete: ${pushResult.pushed} items`);

  const withDeleted = await serverRequest('GET', '/items?includeDeleted=true');
  const serverCopy = withDeleted.items.find(i => i.content === content);
  if (!serverCopy) {
    throw new Error('Server should still hold the row, carrying a tombstone');
  }
  if (!serverCopy.deletedAt || serverCopy.deletedAt <= 0) {
    throw new Error(`Server copy should carry deletedAt > 0, got ${serverCopy.deletedAt}`);
  }
  console.log(`  Server copy carries deletedAt=${serverCopy.deletedAt}`);

  // And the live listing no longer offers it
  if (await serverHasItem(content)) {
    throw new Error('Deleted item should not appear in the default server listing');
  }

  console.log('  PASSED');
}

/**
 * Edge Case Test: Push failures are NOT retried
 *
 * This test documents that if a push fails:
 * - The item is logged as failed
 * - lastSyncTime is still updated
 * - On next sync, the item won't be retried (because updatedAt < lastSyncTime)
 *
 * This is a HIGH PRIORITY issue that could cause data loss.
 */
async function testRejectedItemIsParked() {
  console.log('\n--- Test: Server-Rejected Item Is Parked Until Edited ---');

  // A tagset with no tags is rejected by the server on every attempt: a
  // permanent rejection, which parks the row instead of retrying it forever.
  const { id } = datastore.addItem('tagset', { content: null });
  console.log(`  Created a tagset with no tags: ${id}`);

  await sync.syncAll(BASE_URL, apiKey);

  const parked = datastore.queryItems({}).find(i => i.id === id);
  if (!parked) {
    throw new Error('Tagset row should still exist locally');
  }
  if (!parked.syncError) {
    throw new Error('Rejected item should carry syncError, got empty');
  }
  if (!(parked.syncErrorAt > 0)) {
    throw new Error(`Rejected item should carry syncErrorAt > 0, got ${parked.syncErrorAt}`);
  }
  if (parked.syncId) {
    throw new Error('Rejected item should have no syncId');
  }
  console.log(`  Parked with syncError: ${parked.syncError}`);

  // Parked, so a second run does not attempt it again — the row is unchanged.
  await sync.syncAll(BASE_URL, apiKey);
  const stillParked = datastore.queryItems({}).find(i => i.id === id);
  if (stillParked.syncErrorAt !== parked.syncErrorAt) {
    throw new Error('A parked item should not be re-attempted while unchanged');
  }
  console.log('  Second run left it alone');

  // Editing it moves updatedAt past syncErrorAt, which makes it eligible again.
  const { tag } = datastore.getOrCreateTag('parked-tagset-' + Date.now());
  datastore.tagItem(id, tag.id);
  datastore.updateItem(id, { metadata: { unparked: true } });
  console.log('  Tagged and edited it');

  await sync.syncAll(BASE_URL, apiKey);
  const revived = datastore.queryItems({}).find(i => i.id === id);
  if (!revived.syncId) {
    throw new Error('An edited item should push successfully and earn a syncId');
  }
  console.log(`  Pushed after the edit, syncId=${revived.syncId}`);

  console.log('  PASSED');
}

/**
 * Edge Case Test: Tagset sync (null content by design)
 *
 * Tagsets are items that exist solely to hold tags, with no content.
 * This tests that tagsets sync correctly between desktop and server.
 */
async function testTagsetSync() {
  console.log('\n--- Test: Tagset Sync ---');

  // Create tagset with tags (null content by design)
  const { id: tagsetId } = datastore.addItem('tagset', { content: null });
  const { tag: tag1 } = datastore.getOrCreateTag('tagset-test-1');
  const { tag: tag2 } = datastore.getOrCreateTag('tagset-test-2');
  datastore.tagItem(tagsetId, tag1.id);
  datastore.tagItem(tagsetId, tag2.id);
  console.log(`  Created tagset on desktop: ${tagsetId}`);

  // Verify tagset was created on desktop
  const desktopTagset = datastore.getItem(tagsetId);
  if (!desktopTagset) {
    throw new Error('Tagset not created on desktop');
  }
  if (desktopTagset.type !== 'tagset') {
    throw new Error(`Expected type 'tagset', got '${desktopTagset.type}'`);
  }
  console.log('  Desktop tagset verified');

  // Push to server
  const pushResult = await sync.pushToServer(BASE_URL, apiKey, 0);
  console.log(`  Push complete: ${pushResult.pushed} items`);

  // Verify tagset exists on server
  const serverItems = await serverRequest('GET', '/items');
  const serverTagsets = serverItems.items.filter(i => i.type === 'tagset');

  if (serverTagsets.length > 0) {
    // Find our tagset by checking tags
    const ourTagset = serverTagsets.find(t =>
      t.tags.includes('tagset-test-1') && t.tags.includes('tagset-test-2')
    );

    if (ourTagset) {
      console.log(`  Tagset synced to server with tags: ${ourTagset.tags.join(', ')}`);
    } else {
      console.log(`  Found ${serverTagsets.length} tagsets but none with our test tags`);
      throw new Error('Test tagset not found on server');
    }
  } else {
    throw new Error('No tagsets found on server - tagset sync may be broken');
  }

  console.log('  PASSED');
}

/**
 * Edge Case Test: Unicode and special characters
 *
 * Tests that non-ASCII content syncs correctly including:
 * - Unicode characters (emoji, CJK, etc.)
 * - Special characters
 * - Multi-byte sequences
 */
async function testUnicodeContent() {
  console.log('\n--- Test: Unicode Content Handling ---');

  const unicodeContents = [
    { type: 'text', content: 'Hello 🌍 World 🎉', desc: 'emoji' },
    { type: 'text', content: '日本語テスト', desc: 'Japanese' },
    { type: 'text', content: 'Ελληνικά', desc: 'Greek' },
    { type: 'url', content: 'https://example.com/path?q=日本語', desc: 'URL with unicode' },
    { type: 'text', content: 'Line1\nLine2\tTab', desc: 'control chars' },
  ];

  const createdIds = [];
  for (const item of unicodeContents) {
    const { id } = datastore.addItem(item.type, { content: item.content });
    createdIds.push(id);
    console.log(`  Created ${item.desc}: ${id}`);
  }

  // Push to server
  await sync.pushToServer(BASE_URL, apiKey, 0);
  console.log('  Pushed items to server');

  // Verify all items exist on server with correct content
  let allMatch = true;
  for (const item of unicodeContents) {
    const serverHas = await serverHasItem(item.content);
    if (!serverHas) {
      console.log(`  FAILED: ${item.desc} not found on server`);
      allMatch = false;
    } else {
      console.log(`  OK: ${item.desc} synced correctly`);
    }
  }

  if (!allMatch) {
    throw new Error('Some unicode content failed to sync');
  }

  // Clear desktop and pull from server to verify round-trip
  // (We can't easily clear desktop in this test, so we just verify push worked)

  console.log('  PASSED');
}

/**
 * Edge Case Test: Identical timestamps
 *
 * Tests behavior when server and desktop have items with identical updatedAt.
 * Expected behavior: item is skipped (no update needed).
 */
async function testIdenticalTimestamps() {
  console.log('\n--- Test: Identical Timestamps ---');

  // Create item on server
  const content = 'https://identical-timestamp-' + Date.now() + '.com';
  await serverRequest('POST', '/items', {
    type: 'url',
    content,
    tags: ['timestamp-test'],
  });
  console.log('  Created item on server');

  // Pull to desktop
  const pullResult1 = await sync.pullFromServer(BASE_URL, apiKey);
  console.log(`  First pull: ${pullResult1.pulled} pulled`);

  // Pull again without any changes
  const pullResult2 = await sync.pullFromServer(BASE_URL, apiKey);
  console.log(`  Second pull (no changes): ${pullResult2.pulled} pulled, ${pullResult2.conflicts} conflicts`);

  // The second pull should show 0 pulled (items have identical timestamps)
  // Note: This may show pulled > 0 if the server always returns all items
  // and we re-process them. The key is no duplicates are created.

  // Verify no duplicates
  const desktopItems = datastore.queryItems({});
  const matchingItems = desktopItems.filter(i => i.content === content);
  if (matchingItems.length !== 1) {
    throw new Error(`Expected 1 item on desktop, got ${matchingItems.length}`);
  }

  console.log('  No duplicates created on repeated pull');
  console.log('  PASSED');
}

// ==================== Real-Socket Tag/Event/Batch-Fallback Tests ====================
//
// See docs/sync-coverage-gaps.md §8: every tag/event stage assertion previously
// lived only in the in-process suite (sync.test.ts), which stubs fetch straight
// into the server's Hono app and so cannot see a client/server disagreement over
// an actual socket. The tests below call the real pushTagsToServer() /
// pullTagsFromServer() / pushEventsToServer() / pullEventsFromServer() against
// the spawned server, and request the tag-metadata and event routes directly
// through serverRequest() to confirm what actually crossed the wire.

/**
 * Edge Case Test: Tag metadata stages over a real socket
 *
 * testTagsetSync() above covers the `tags` array on POST /items; it never
 * touches the tag-metadata routes (GET/POST /tags, GET /tags/since). This test
 * does: push local tag metadata and confirm it lands via GET /tags/since/0,
 * then create tag metadata server-side and confirm pullTagsFromServer() merges
 * it into the local datastore.
 */
async function testTagStagesOverSocket() {
  console.log('\n--- Test: Tag Metadata Stages Over Socket ---');

  // Push: create local tag metadata, push it, and read it back through the
  // tag-metadata route directly — not through /items.
  const localTagName = 'e2e-tag-push-' + Date.now();
  const { tag: localTag } = datastore.getOrCreateTag(localTagName);
  datastore.updateTagColor(localTag.id, '#ff00ff');
  console.log(`  Created local tag metadata: ${localTagName}`);

  const pushResult = await sync.pushTagsToServer(BASE_URL, apiKey);
  console.log(`  pushTagsToServer: ${pushResult.pushed} pushed`);

  const sinceRes = await serverRequest('GET', '/tags/since/0');
  const serverTag = sinceRes.tags.find(t => t.name === localTagName);
  if (!serverTag) {
    throw new Error(`Tag metadata for '${localTagName}' not found via GET /tags/since/0 after push`);
  }
  if (serverTag.color !== '#ff00ff') {
    throw new Error(`Expected pushed color #ff00ff, got ${serverTag.color}`);
  }
  console.log('  Tag metadata arrived over the socket via /tags/since');

  // Pull: create tag metadata on the server only, then confirm the real pull
  // stage merges it into the local tags table.
  const serverTagName = 'e2e-tag-pull-' + Date.now();
  await serverRequest('POST', '/tags', {
    tags: [{
      name: serverTagName,
      slug: 'e2e-pull-slug',
      color: '#00ff00',
      description: 'pulled over a real socket',
      updatedAt: Date.now(),
    }],
  });
  console.log(`  Created tag metadata on server: ${serverTagName}`);

  const pullResult = await sync.pullTagsFromServer(BASE_URL, apiKey);
  console.log(`  pullTagsFromServer: ${pullResult.pulled} pulled`);

  const localRow = datastore.getDb().prepare('SELECT * FROM tags WHERE name = ?').get(serverTagName);
  if (!localRow) {
    throw new Error(`Tag '${serverTagName}' not found locally after pull`);
  }
  if (localRow.color !== '#00ff00') {
    throw new Error(`Expected pulled color #00ff00, got ${localRow.color}`);
  }

  console.log('  PASSED');
}

/**
 * Edge Case Test: item_events stages over a real socket
 *
 * No prior e2e test calls pushEventsToServer()/pullEventsFromServer() or
 * requests /events/since directly — those stages only ran incidentally inside
 * syncAll(). This test drives both directions explicitly: an item earns a
 * syncId, its item_events rows push and are confirmed via GET /events/since/0,
 * then a server-side event pulls down and merges into the local datastore.
 */
async function testEventStagesOverSocket() {
  console.log('\n--- Test: Event Stages Over Socket ---');

  // Push: the parent item needs a syncId before its events can address it on
  // the wire (itemId there is always the SERVER's item id).
  const content = 'https://event-stage-' + Date.now() + '.com';
  const { id: itemId } = datastore.addItem('url', { content });
  await sync.pushToServer(BASE_URL, apiKey, 0);
  const desktopItem = getDesktopItem(content);
  if (!desktopItem || !desktopItem.syncId) {
    throw new Error('Item should have earned a syncId before its events can push');
  }
  console.log(`  Item pushed, syncId=${desktopItem.syncId}`);

  const { id: eventId } = datastore.addItemEvent(itemId, { content: 'e2e-event', value: 7 });
  console.log(`  Created local item_events row: ${eventId}`);

  const pushResult = await sync.pushEventsToServer(BASE_URL, apiKey);
  console.log(`  pushEventsToServer: ${pushResult.pushed} pushed, ${pushResult.failed} failed`);

  const sinceRes = await serverRequest('GET', '/events/since/0');
  const serverEvent = sinceRes.events.find(e => e.id === eventId);
  if (!serverEvent) {
    throw new Error(`Event ${eventId} not found via GET /events/since/0 after push`);
  }
  if (serverEvent.itemId !== desktopItem.syncId) {
    throw new Error(`Server event itemId should be the item's syncId (${desktopItem.syncId}), got ${serverEvent.itemId}`);
  }
  console.log('  Event arrived over the socket via /events/since');

  // Pull: create an event on the server against that same synced item, and
  // confirm the real pull stage merges it into the local item_events table.
  const serverEventId = 'e2e-server-event-' + Date.now();
  await serverRequest('POST', '/events', {
    events: [{
      id: serverEventId,
      itemId: desktopItem.syncId,
      content: 'e2e-server-side',
      value: 42,
      occurredAt: Date.now(),
      createdAt: Date.now(),
    }],
  });
  console.log(`  Created event on server: ${serverEventId}`);

  const pullResult = await sync.pullEventsFromServer(BASE_URL, apiKey);
  console.log(`  pullEventsFromServer: ${pullResult.pulled} pulled`);

  const localRow = datastore.getDb().prepare('SELECT * FROM item_events WHERE id = ?').get(serverEventId);
  if (!localRow) {
    throw new Error(`Event ${serverEventId} not found locally after pull`);
  }
  if (localRow.itemId !== itemId) {
    throw new Error(`Pulled event should attach to local item ${itemId}, got ${localRow.itemId}`);
  }

  console.log('  PASSED');
}

/**
 * Edge Case Test: item_events.pushedAt stamping over a real socket
 *
 * docs/sync-coverage-gaps.md §2: pushEventsToServer() stamps delivery per row
 * rather than against a watermark, specifically so an event whose parent item
 * has no syncId yet strands exactly itself instead of holding back every event
 * behind it. This proves both halves against the real server: a delivered
 * event's pushedAt moves off zero, and a stranded event's does not.
 */
async function testEventPushedAtStamping() {
  console.log('\n--- Test: Event pushedAt Stamping ---');

  // Delivered: parent item already carries a syncId.
  const syncedContent = 'https://pushedat-synced-' + Date.now() + '.com';
  const { id: syncedItemId } = datastore.addItem('url', { content: syncedContent });
  await sync.pushToServer(BASE_URL, apiKey, 0);
  const syncedItem = getDesktopItem(syncedContent);
  if (!syncedItem || !syncedItem.syncId) {
    throw new Error('Item should have earned a syncId before its event can push');
  }
  const { id: deliveredEventId } = datastore.addItemEvent(syncedItemId, { content: 'delivered' });

  // Stranded: parent item has never synced, so pushEventsToServer() must skip
  // its event rather than sending an itemId the server has never seen.
  const unsyncedContent = 'https://pushedat-unsynced-' + Date.now() + '.com';
  const { id: unsyncedItemId } = datastore.addItem('url', { content: unsyncedContent });
  const { id: strandedEventId } = datastore.addItemEvent(unsyncedItemId, { content: 'stranded' });

  await sync.pushEventsToServer(BASE_URL, apiKey);

  const db = datastore.getDb();
  const delivered = db.prepare('SELECT pushedAt FROM item_events WHERE id = ?').get(deliveredEventId);
  if (!delivered || !(delivered.pushedAt > 0)) {
    throw new Error(`Delivered event should carry pushedAt > 0, got ${delivered && delivered.pushedAt}`);
  }
  console.log(`  Delivered event stamped pushedAt=${delivered.pushedAt}`);

  const stranded = db.prepare('SELECT pushedAt FROM item_events WHERE id = ?').get(strandedEventId);
  if (!stranded || stranded.pushedAt !== 0) {
    throw new Error(`Event whose parent has no syncId should stay at pushedAt = 0, got ${stranded && stranded.pushedAt}`);
  }
  console.log('  Event with an unsynced parent stayed at pushedAt = 0, stranded exactly itself');

  console.log('  PASSED');
}

/**
 * A tiny transparent proxy in front of the real server, used only by
 * testBatchFallbackWhenRouteMissing() below. It answers POST /items/batch with
 * a bare 404 (as an older, pre-batch server would) and forwards every other
 * request — method, path, query, headers, body — to the real server, piping
 * the response status/headers/body straight back.
 */
function startBatchFallbackProxy() {
  return new Promise((resolve, reject) => {
    // Counts what the proxy actually saw, so a caller can tell the fallback was
    // really traversed rather than inferring it from where the items ended up —
    // items landing on the real server is also what a proxy that never faked the
    // 404 at all would produce, which is exactly the "prints a pass on every
    // path" shape docs/sync-coverage-gaps.md §8 warns about.
    const counts = { batchAttempts: 0, singleRequests: 0 };

    const server = http.createServer((req, res) => {
      const chunks = [];
      req.on('data', (chunk) => chunks.push(chunk));
      req.on('end', () => {
        const body = Buffer.concat(chunks);
        const path = req.url.split('?')[0];

        if (req.method === 'POST' && path === '/items/batch') {
          counts.batchAttempts++;
          log('Proxy: faking 404 for POST /items/batch');
          res.writeHead(404, { 'Content-Type': 'application/json' });
          res.end(JSON.stringify({ error: 'no such route (proxy fake)' }));
          return;
        }

        if (req.method === 'POST' && path === '/items') {
          counts.singleRequests++;
        }

        const upstream = http.request(
          { host: '127.0.0.1', port: TEST_PORT, method: req.method, path: req.url, headers: req.headers },
          (upstreamRes) => {
            res.writeHead(upstreamRes.statusCode, upstreamRes.headers);
            upstreamRes.pipe(res);
          }
        );
        upstream.on('error', (err) => {
          res.writeHead(502);
          res.end(String(err));
        });
        upstream.end(body);
      });
    });
    server.on('error', reject);
    server.listen(0, '127.0.0.1', () => {
      const { port } = server.address();
      resolve({ server, url: `http://127.0.0.1:${port}`, counts });
    });
  });
}

/**
 * Edge Case Test: POST /items/batch 404 fallback, proven over a real socket
 *
 * The spawned server always has the batch route, so pushToServer()'s per-item
 * fallback (triggered when a chunk request comes back 404) is unreachable
 * against it directly. Routing the push through startBatchFallbackProxy()
 * instead makes the 404 real, over an actual socket, and this test confirms
 * both that the client actually attempted the batch route and got a real 404
 * for it, and that every item still landed on the real server through the
 * per-item route the fallback switches to — items landing alone would also be
 * true of a proxy that never faked the 404, so that check on its own proves
 * nothing about the fallback path specifically.
 */
async function testBatchFallbackWhenRouteMissing() {
  console.log('\n--- Test: POST /items/batch 404 Fallback Over Socket ---');

  const { server: proxyServer, url: proxyUrl, counts } = await startBatchFallbackProxy();
  console.log(`  Proxy listening at ${proxyUrl}, faking 404 on POST /items/batch`);

  try {
    const contents = [];
    for (let i = 0; i < 3; i++) {
      const content = `https://batch-fallback-${Date.now()}-${i}.com`;
      datastore.addItem('url', { content });
      contents.push(content);
    }
    console.log(`  Created ${contents.length} items on desktop`);

    // pushToServer() takes the server URL as an explicit argument (every push/pull
    // stage in this module does — see pushTagsToServer()/pushEventsToServer()
    // above), so routing through the proxy needs no global sync-config change.
    const pushResult = await sync.pushToServer(proxyUrl, apiKey, 0);
    console.log(`  pushToServer via proxy: ${pushResult.pushed} pushed, ${pushResult.failed} failed`);
    console.log(`  Proxy saw ${counts.batchAttempts} batch attempt(s), ${counts.singleRequests} single-item request(s)`);

    if (pushResult.failed > 0) {
      throw new Error(`Expected every item to land through the per-item fallback, got ${pushResult.failed} failed`);
    }

    // Chunking could split this run's items across more than one batch attempt,
    // so >= 1 rather than === 1 — the point is that the client tried the batch
    // route and really got a 404 over the socket, not how many chunks it took.
    if (counts.batchAttempts < 1) {
      throw new Error('Expected the client to attempt POST /items/batch at least once before falling back');
    }
    // Every item pushToServer() reports as delivered must have gone out as its
    // own POST /items — that is the fallback actually being traversed, not just
    // items ending up on the server by some other route.
    if (counts.singleRequests !== pushResult.pushed) {
      throw new Error(`Expected ${pushResult.pushed} per-item POST /items request(s) from the fallback, saw ${counts.singleRequests}`);
    }

    for (const content of contents) {
      if (!(await serverHasItem(content))) {
        throw new Error(`Item not found on the real server after the batch-route fallback: ${content}`);
      }
    }
    console.log('  Every item landed on the real server through the per-item fallback');

    console.log('  PASSED');
  } finally {
    proxyServer.close();
  }
}

// ==================== Test Runner ====================

async function runTests() {
  console.log('='.repeat(60));
  console.log('Desktop <-> Server Sync E2E Tests');
  console.log('='.repeat(60));

  let passed = 0;
  let failed = 0;
  const failures = [];

  try {
    await startServer();
    await initDesktopDatastore();

    const tests = [
      ['Server to Desktop Pull', testServerToDesktopPull],
      ['Desktop to Server Push', testDesktopToServerPush],
      ['Bidirectional Sync', testBidirectionalSync],
      ['Conflict - Server Newer Wins', testConflictServerNewerWins],
      ['Conflict - Desktop Newer Wins', testConflictDesktopNewerWins],
      ['Incremental Sync', testIncrementalSync],
      ['sync_id Duplicate Prevention', testSyncIdDuplicatePrevention],
      ['sync_id Based Deduplication', testSyncIdDeduplication],
      // Edge case tests
      ['Deletion Tombstone Propagates', testDeletionTombstonePropagates],
      ['Server-Rejected Item Is Parked', testRejectedItemIsParked],
      ['Tagset Sync', testTagsetSync],
      ['Unicode Content Handling', testUnicodeContent],
      ['Identical Timestamps', testIdenticalTimestamps],
      // Real-socket tag/event/batch-fallback tests
      ['Tag Metadata Stages Over Socket', testTagStagesOverSocket],
      ['Event Stages Over Socket', testEventStagesOverSocket],
      ['Event pushedAt Stamping', testEventPushedAtStamping],
      ['POST /items/batch 404 Fallback Over Socket', testBatchFallbackWhenRouteMissing],
    ];

    for (const [name, testFn] of tests) {
      try {
        await testFn();
        passed++;
      } catch (error) {
        failed++;
        failures.push({ name, error: error.message });
        console.error(`  FAILED: ${name}`);
        console.error(`    Error: ${error.message}`);
        if (process.env.VERBOSE) {
          console.error(error.stack);
        }
      }
    }
  } finally {
    await cleanupDesktop();
    await stopServer();
  }

  // Summary
  console.log('\n' + '='.repeat(60));
  console.log(`Results: ${passed} passed, ${failed} failed`);

  if (failures.length > 0) {
    console.log('\nFailures:');
    for (const { name, error } of failures) {
      console.log(`  - ${name}: ${error}`);
    }
    console.log('='.repeat(60));
    process.exit(1);
  } else {
    console.log('\nAll tests passed!');
    console.log('='.repeat(60));
    process.exit(0);
  }
}

// Handle cleanup on exit
process.on('SIGINT', async () => {
  console.log('\nInterrupted, cleaning up...');
  await cleanupDesktop();
  await stopServer();
  process.exit(1);
});

process.on('SIGTERM', async () => {
  await cleanupDesktop();
  await stopServer();
  process.exit(1);
});

// Run tests
runTests().catch(async (error) => {
  console.error('Test runner error:', error);
  await cleanupDesktop();
  await stopServer();
  process.exit(1);
});