@crawlith/core 0.1.0

package/tests/duplicate.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, expect } from 'vitest';
+import { Graph } from '../src/graph/graph.js';
+import { detectDuplicates } from '../src/graph/duplicate.js';
+import { SimHash } from '../src/graph/simhash.js';
+
+describe('Duplicate Detection', () => {
+    it('should detect exact duplicates based on contentHash', () => {
+        const graph = new Graph();
+        graph.addNode('https://example.com/a', 0, 200);
+        graph.addNode('https://example.com/b', 0, 200);
+        graph.addNode('https://example.com/c', 0, 200);
+
+        graph.updateNodeData('https://example.com/a', { contentHash: 'hash1', uniqueTokenRatio: 1.0 });
+        graph.updateNodeData('https://example.com/b', { contentHash: 'hash1', uniqueTokenRatio: 1.0 });
+        graph.updateNodeData('https://example.com/c', { contentHash: 'hash2', uniqueTokenRatio: 1.0 });
+
+        detectDuplicates(graph);
+
+        expect(graph.duplicateClusters).toHaveLength(1);
+        const cluster = graph.duplicateClusters[0];
+        expect(cluster.type).toBe('exact');
+        expect(cluster.size).toBe(2);
+
+        const nodeA = graph.nodes.get('https://example.com/a')!;
+        const nodeB = graph.nodes.get('https://example.com/b')!;
+        expect(nodeA.duplicateClusterId).toBeDefined();
+        expect(nodeA.duplicateClusterId).toBe(nodeB.duplicateClusterId);
+
+        // One should be primary, one should be collapsed
+        expect(!nodeA.isCollapsed !== !nodeB.isCollapsed).toBe(true);
+    });
+
+    it('should detect near duplicates using SimHash', () => {
+        const graph = new Graph();
+        graph.addNode('https://example.com/x', 0, 200);
+        graph.addNode('https://example.com/y', 0, 200);
+
+        // Calculate simhashes that are 1 bit apart
+        const tokens1 = ['hello', 'world', 'this', 'is', 'a', 'test', 'document'];
+        const tokens2 = ['hello', 'world', 'this', 'is', 'a', 'test', 'document2'];
+
+        const h1 = SimHash.generate(tokens1);
+        const h2 = SimHash.generate(tokens2);
+
+        // Assume standard text gives < 3 diff. For reliability in test, we'll manually set string bigint representations.
+        // Actually, we can just use the calculated ones.
+        graph.updateNodeData('https://example.com/x', { contentHash: 'x', simhash: h1.toString(), uniqueTokenRatio: 1.0 });
+        graph.updateNodeData('https://example.com/y', { contentHash: 'y', simhash: h2.toString(), uniqueTokenRatio: 1.0 });
+
+        detectDuplicates(graph, { simhashThreshold: 10 }); // use high threshold to guarantee match
+
+        expect(graph.duplicateClusters).toHaveLength(1);
+        expect(graph.duplicateClusters[0].type).toBe('near');
+    });
+
+    it('should identify template-heavy clusters', () => {
+        const graph = new Graph();
+        graph.addNode('https://example.com/1', 0, 200);
+        graph.addNode('https://example.com/2', 0, 200);
+
+        graph.updateNodeData('https://example.com/1', { contentHash: 'h1', uniqueTokenRatio: 0.2 });
+        graph.updateNodeData('https://example.com/2', { contentHash: 'h1', uniqueTokenRatio: 0.2 });
+
+        detectDuplicates(graph);
+
+        expect(graph.duplicateClusters[0].type).toBe('template_heavy');
+    });
+
+    it('should mark high severity on missing canonicals', () => {
+        const graph = new Graph();
+        graph.addNode('https://example.com/a', 0, 200);
+        graph.addNode('https://example.com/b', 0, 200);
+
+        graph.updateNodeData('https://example.com/a', { contentHash: 'h1', canonical: 'https://example.com/a' });
+        graph.updateNodeData('https://example.com/b', { contentHash: 'h1', canonical: undefined }); // missing
+
+        detectDuplicates(graph);
+
+        expect(graph.duplicateClusters[0].severity).toBe('high');
+    });
+
+    it('should transfer edges during collapse', () => {
+        const graph = new Graph();
+        graph.addNode('https://example.com/a', 0, 200);
+        graph.addNode('https://example.com/b', 0, 200);
+        graph.addNode('https://example.com/source', 0, 200);
+
+        graph.updateNodeData('https://example.com/a', { contentHash: 'h1' });
+        graph.updateNodeData('https://example.com/b', { contentHash: 'h1' });
+
+        // Add edge pointing to B
+        graph.edges.set('https://example.com/source|https://example.com/b', 1);
+
+        // Force A to be the representative by giving it higher inLinks manually, though it's determined dynamically
+        graph.nodes.get('https://example.com/a')!.inLinks = 10;
+
+        detectDuplicates(graph);
+
+        const a = graph.nodes.get('https://example.com/a')!;
+        const b = graph.nodes.get('https://example.com/b')!;
+
+        expect(a.isClusterPrimary).toBe(true);
+        expect(a.isCollapsed).toBe(false);
+        expect(b.isCollapsed).toBe(true);
+        expect(b.collapseInto).toBe('https://example.com/a');
+
+        // Check edge transfer
+        expect(graph.edges.has('https://example.com/source|https://example.com/a')).toBe(true);
+    });
+});

package/tests/fetcher.test.ts

@@ -0,0 +1,106 @@
+import { test, expect, beforeEach } from 'vitest';
+import { Fetcher } from '../src/crawler/fetcher.js';
+import { MockAgent, setGlobalDispatcher } from 'undici';
+
+let mockAgent: MockAgent;
+
+beforeEach(() => {
+  mockAgent = new MockAgent();
+  mockAgent.disableNetConnect();
+  setGlobalDispatcher(mockAgent);
+});
+
+test('fetches simple page', async () => {
+  const client = mockAgent.get('https://example.com');
+  client.intercept({ path: '/', method: 'GET' }).reply(200, 'Hello', {
+    headers: { 'content-type': 'text/html', 'etag': '"123"', 'last-modified': 'Mon, 01 Jan 2000 00:00:00 GMT' }
+  });
+
+  const fetcher = new Fetcher();
+  const res = await fetcher.fetch('https://example.com/');
+  expect(res.status).toBe(200);
+  expect(res.body).toBe('Hello');
+  expect(res.etag).toBe('"123"');
+  expect(res.lastModified).toBe('Mon, 01 Jan 2000 00:00:00 GMT');
+  expect(res.redirectChain).toEqual([]);
+});
+
+test('follows redirects', async () => {
+  const client = mockAgent.get('https://example.com');
+  // A -> B
+  client.intercept({ path: '/a', method: 'GET' }).reply(301, '', {
+    headers: { location: '/b' }
+  });
+  // B -> C
+  client.intercept({ path: '/b', method: 'GET' }).reply(302, '', {
+    headers: { location: 'https://other.com/c' }
+  });
+
+  const otherClient = mockAgent.get('https://other.com');
+  // C -> 200
+  otherClient.intercept({ path: '/c', method: 'GET' }).reply(200, 'Final');
+
+  const fetcher = new Fetcher();
+  const res = await fetcher.fetch('https://example.com/a');
+
+  expect(res.status).toBe(200);
+  expect(res.body).toBe('Final');
+  expect(res.finalUrl).toBe('https://other.com/c');
+  expect(res.redirectChain.length).toBe(2);
+  expect(res.redirectChain[0]).toEqual({ url: 'https://example.com/a', status: 301, target: 'https://example.com/b' });
+  expect(res.redirectChain[1]).toEqual({ url: 'https://example.com/b', status: 302, target: 'https://other.com/c' });
+});
+
+test('detects redirect loop', async () => {
+  const client = mockAgent.get('https://loop.com');
+  // A -> B
+  client.intercept({ path: '/a', method: 'GET' }).reply(301, '', { headers: { location: '/b' } });
+  // B -> A (This will be detected as loop)
+  client.intercept({ path: '/b', method: 'GET' }).reply(301, '', { headers: { location: '/a' } });
+
+  const fetcher = new Fetcher();
+  const res = await fetcher.fetch('https://loop.com/a');
+
+  // Should return the redirect_loop security error
+  expect(res.status).toBe('redirect_loop');
+  expect(res.redirectChain.length).toBe(1); // Detected while resolving target of B
+  expect(res.redirectChain[0].url).toBe('https://loop.com/a');
+});
+
+test('sends conditional headers', async () => {
+  const client = mockAgent.get('https://cache.com');
+
+  client.intercept({
+    path: '/',
+    method: 'GET',
+    headers: {
+      'If-None-Match': '"123"',
+      'If-Modified-Since': 'Mon, 01 Jan 2000 00:00:00 GMT'
+    }
+  }).reply(304, '', { headers: { etag: '"123"' } });
+
+  const fetcher = new Fetcher();
+  const res = await fetcher.fetch('https://cache.com/', {
+    etag: '"123"',
+    lastModified: 'Mon, 01 Jan 2000 00:00:00 GMT'
+  });
+
+  expect(res.status).toBe(304);
+  expect(res.body).toBe('');
+});
+
+test('handles max redirects', async () => {
+  const client = mockAgent.get('https://max.com');
+  // 11 redirects
+  for (let i = 0; i < 11; i++) {
+    client.intercept({ path: `/p${i}`, method: 'GET' }).reply(301, '', { headers: { location: `/p${i + 1}` } });
+  }
+
+  // Set maxRedirects to 10 to trigger failure exactly after 10 hops
+  // Increase rate to prevent timeout (11 requests * 500ms > 5000ms)
+  const fetcher = new Fetcher({ maxRedirects: 10, rate: 100 });
+  const res = await fetcher.fetch('https://max.com/p0');
+
+  expect(res.status).toBe('redirect_limit_exceeded');
+  expect(res.redirectChain.length).toBe(10);
+});

package/tests/fetcher_safety.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Fetcher } from '../src/crawler/fetcher.js';
+import { request } from 'undici';
+
+vi.mock('undici', () => ({
+    request: vi.fn(),
+}));
+
+describe('Fetcher Safety Integration', () => {
+    let fetcher: Fetcher;
+
+    beforeEach(() => {
+        vi.clearAllMocks();
+        fetcher = new Fetcher({ rate: 100 }); // High rate for tests
+    });
+
+    it('should block internal IPs', async () => {
+        const res = await fetcher.fetch('http://127.0.0.1');
+        expect(res.status).toBe('blocked_internal_ip');
+    });
+
+    it('should block internal IPs in redirects', async () => {
+        const mockRequest = vi.mocked(request);
+
+        // First request is fine, returns redirect
+        mockRequest.mockResolvedValueOnce({
+            statusCode: 301,
+            headers: { location: 'http://192.168.1.1' },
+            body: { dump: vi.fn(), text: vi.fn().mockResolvedValue('') }
+        } as any);
+
+        const res = await fetcher.fetch('http://example.com');
+        expect(res.status).toBe('blocked_internal_ip');
+        expect(res.redirectChain).toHaveLength(1); // Records the redirect that led to block
+        expect(res.redirectChain[0].target).toBe('http://192.168.1.1/');
+    });
+
+    it('should enforce max bytes', async () => {
+        const mockRequest = vi.mocked(request);
+
+        mockRequest.mockResolvedValueOnce({
+            statusCode: 200,
+            headers: {},
+            body: {
+                on: vi.fn((event, cb) => {
+                    if (event === 'data') {
+                        cb(Buffer.alloc(1000));
+                        cb(Buffer.alloc(1000));
+                    }
+                    return { on: vi.fn() };
+                }),
+                destroy: vi.fn(),
+                dump: vi.fn()
+            }
+        } as any);
+
+        const res = await fetcher.fetch('http://example.com', { maxBytes: 500 });
+        expect(res.status).toBe('oversized');
+    });
+
+    it('should retry on 500', async () => {
+        const mockRequest = vi.mocked(request);
+
+        mockRequest
+            .mockResolvedValueOnce({
+                statusCode: 500,
+                headers: {},
+                body: { dump: vi.fn().mockResolvedValue(undefined) }
+            } as any)
+            .mockResolvedValueOnce({
+                statusCode: 200,
+                headers: {},
+                body: {
+                    on: vi.fn((event, cb) => {
+                        if (event === 'data') cb(Buffer.from('ok'));
+                        if (event === 'end') cb();
+                    })
+                }
+            } as any);
+
+        const res = await fetcher.fetch('http://example.com');
+        expect(res.status).toBe(200);
+        expect(res.retries).toBe(1);
+    });
+});

package/tests/fixtures/analyze-crawl.json

@@ -0,0 +1,26 @@
+{
+  "pages": [
+    {
+      "url": "https://example.com/",
+      "status": 200,
+      "depth": 0,
+      "html": "<html><head><title>Example Home Page SEO Title For Strong Ranking Signals 12345</title><meta name='description' content='This is an intentionally long and descriptive meta description designed to fit ideal search snippet lengths with rich context for users and engines.'/></head><body><h1>Home</h1><nav><a href='/skip'>Nav</a></nav><p>Welcome to the homepage. This page contains meaningful content. Another sentence here.</p><img src='/a.jpg' alt='hero'><img src='/b.jpg'><a href='/about'>About</a><a href='https://external.com' rel='nofollow noopener'>External</a><script type='application/ld+json'>{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\"}</script></body></html>"
+    },
+    {
+      "url": "https://example.com/about",
+      "status": 200,
+      "depth": 1,
+      "html": "<html><head><title>Example Home Page SEO Title For Strong Ranking Signals 12345</title><meta name='description' content='short desc'/></head><body><h1>Example Home Page SEO Title For Strong Ranking Signals 12345</h1><h1>Second</h1><p>Duplicate body sentence. Duplicate body sentence.</p><img src='/c.jpg' alt=''><script type='application/ld+json'>not-json</script><a href='https://example.com/'>Home</a></body></html>"
+    },
+    {
+      "url": "https://example.com/empty",
+      "status": 200,
+      "depth": 2,
+      "html": ""
+    }
+  ],
+  "edges": [
+    { "source": "https://example.com/", "target": "https://example.com/about" },
+    { "source": "https://example.com/about", "target": "https://example.com/" }
+  ]
+}

package/tests/hits.test.ts

@@ -0,0 +1,134 @@
+import { describe, it, expect } from 'vitest';
+import { Graph } from '../src/graph/graph.js';
+import { computeHITS } from '../src/scoring/hits.js';
+
+describe('HITS Scoring', () => {
+    it('should compute scores for a simple star topology', () => {
+        const graph = new Graph();
+        // Hub
+        graph.addNode('http://hub.com', 0, 200);
+        // Authorities
+        graph.addNode('http://auth1.com', 1, 200);
+        graph.addNode('http://auth2.com', 1, 200);
+        graph.addNode('http://auth3.com', 1, 200);
+
+        graph.addEdge('http://hub.com', 'http://auth1.com');
+        graph.addEdge('http://hub.com', 'http://auth2.com');
+        graph.addEdge('http://hub.com', 'http://auth3.com');
+
+        computeHITS(graph, { iterations: 10 });
+
+        const hub = graph.nodes.get('http://hub.com')!;
+        const auth1 = graph.nodes.get('http://auth1.com')!;
+
+        // In a star topology:
+        // Hub should have max hub score
+        // Authorities should have max authority scores
+        expect(hub.hubScore).toBeGreaterThan(0.9);
+        expect(hub.authorityScore).toBe(0); // No one links to hub
+
+        expect(auth1.authorityScore).toBeGreaterThan(0.5);
+        expect(auth1.hubScore).toBe(0); // Auth1 links to no one
+    });
+
+    it('should handle exclusion rules', () => {
+        const graph = new Graph();
+        graph.addNode('http://valid.com', 0, 200);
+        graph.addNode('http://noindex.com', 0, 200);
+        graph.updateNodeData('http://noindex.com', { noindex: true });
+        graph.addNode('http://redirect.com', 0, 200);
+        graph.updateNodeData('http://redirect.com', { redirectChain: ['http://target.com'] });
+        graph.addNode('http://external.com', 0, 200); // Eligibility check marks it as eligible if status is 200 
+        // but typically external wouldn't have status 200 in the graph if we don't crawl them or they are marked as external.
+        // The current hits logic relies on: status === 200 && no redirectChain && !noindex
+
+        graph.addEdge('http://valid.com', 'http://noindex.com');
+        graph.addEdge('http://valid.com', 'http://redirect.com');
+
+        computeHITS(graph);
+
+        expect(graph.nodes.get('http://noindex.com')?.hubScore).toBeUndefined();
+        expect(graph.nodes.get('http://redirect.com')?.hubScore).toBeUndefined();
+        expect(graph.nodes.get('http://valid.com')?.hubScore).toBe(0); // Valid hub but its targets are ineligible
+    });
+
+    it('should respect edge weights', () => {
+        const graph = new Graph();
+        graph.addNode('http://hub.com', 0, 200);
+        graph.addNode('http://auth-high.com', 1, 200);
+        graph.addNode('http://auth-low.com', 1, 200);
+
+        graph.addEdge('http://hub.com', 'http://auth-high.com', 1.0);
+        graph.addEdge('http://hub.com', 'http://auth-low.com', 0.1);
+
+        computeHITS(graph, { iterations: 10 });
+
+        const authHigh = graph.nodes.get('http://auth-high.com')!;
+        const authLow = graph.nodes.get('http://auth-low.com')!;
+
+        expect(authHigh.authorityScore).toBeGreaterThan(authLow.authorityScore!);
+    });
+
+    it('should classify link roles correctly', () => {
+        const graph = new Graph();
+        for (let i = 0; i < 11; i++) {
+            graph.addNode(`http://node${i}.com`, 0, 200);
+        }
+
+        // AUTHORITY: node1 (linked by 0,2,3... no outlinks)
+        graph.addEdge('http://node0.com', 'http://node1.com');
+        graph.addEdge('http://node2.com', 'http://node1.com');
+        graph.addEdge('http://node3.com', 'http://node1.com');
+        graph.addEdge('http://node4.com', 'http://node1.com');
+
+        // HUB: node4 (links to 1,5,6,7... few inlinks)
+        graph.addEdge('http://node4.com', 'http://node5.com');
+        graph.addEdge('http://node4.com', 'http://node6.com');
+        graph.addEdge('http://node4.com', 'http://node7.com');
+
+        // POWER: node2 (linked by 0, power is often recursive... link to authority and be linked by hub)
+        graph.addEdge('http://node0.com', 'http://node2.com');
+        graph.addEdge('http://node2.com', 'http://node1.com');
+        graph.addEdge('http://node2.com', 'http://node5.com');
+
+        // PERIPHERAL: node10 (no links)
+        // Some filler nodes to push medians down
+        graph.addEdge('http://node8.com', 'http://node9.com');
+
+        computeHITS(graph, { iterations: 20 });
+
+        const roles = graph.getNodes().map(n => n.linkRole).filter(Boolean);
+        expect(roles).toContain('authority');
+        expect(roles).toContain('hub');
+        expect(roles).toContain('power');
+        expect(roles).toContain('peripheral');
+    });
+
+    it('should handle large synthetic graphs (Performance Test)', () => {
+        const graph = new Graph();
+        const nodeCount = 5000;
+
+        // Create 5000 nodes
+        for (let i = 0; i < nodeCount; i++) {
+            graph.addNode(`http://page${i}.com`, 1, 200);
+        }
+
+        // Create random edges (avg 10 per node)
+        for (let i = 0; i < nodeCount; i++) {
+            for (let j = 0; j < 10; j++) {
+                const target = Math.floor(Math.random() * nodeCount);
+                if (i !== target) {
+                    graph.addEdge(`http://page${i}.com`, `http://page${target}.com`);
+                }
+            }
+        }
+
+        const start = Date.now();
+        computeHITS(graph, { iterations: 20 });
+        const duration = Date.now() - start;
+
+        console.log(`HITS on 5000 nodes took ${duration}ms`);
+        expect(duration).toBeLessThan(2000); // Should be very fast, but allow buffer for CI environments
+        expect(graph.nodes.get('http://page0.com')?.hubScore).toBeDefined();
+    });
+});

package/tests/html_report.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from 'vitest';
+import { generateHtml } from '../src/report/html.js';
+import { Metrics } from '../src/graph/metrics.js';
+
+describe('html report generator', () => {
+    test('generates valid html string with metrics', () => {
+        const mockMetrics: Metrics = {
+            totalPages: 10,
+            totalEdges: 20,
+            orphanPages: ['https://example.com/orphan'],
+            nearOrphans: [],
+            deepPages: [],
+            topAuthorityPages: [{ url: 'https://example.com/', authority: 0.9 }],
+            averageOutDegree: 2.0,
+            maxDepthFound: 5,
+            crawlEfficiencyScore: 0.8,
+            averageDepth: 3.0,
+            structuralEntropy: 1.5,
+            topPageRankPages: [],
+            limitReached: false,
+            sessionStats: {
+                pagesFetched: 5,
+                pagesCached: 2,
+                pagesSkipped: 0,
+                totalFound: 7
+            }
+        };
+
+        const mockGraphData = {
+            nodes: [{ url: 'https://example.com/', depth: 0, inLinks: 5, outLinks: 2, status: 200 }],
+            edges: []
+        };
+
+        const html = generateHtml(mockGraphData, mockMetrics);
+
+        expect(html).toContain('<!DOCTYPE html>');
+        expect(html).toContain('Crawlith Site Graph');
+        expect(html).toContain('10</span>'); // totalPages
+        expect(html).toContain('5 pages</span>'); // pagesFetched
+        expect(html).toContain('2</span>'); // pagesCached
+        expect(html).toContain('https://example.com/orphan');
+        expect(html).toContain('window.GRAPH_DATA =');
+    });
+
+    test('handles missing session stats', () => {
+        const mockMetrics: any = {
+            totalPages: 10,
+            totalEdges: 20,
+            orphanPages: [],
+            averageOutDegree: 2.0,
+            maxDepthFound: 5,
+            topAuthorityPages: [],
+            sessionStats: null
+        };
+        const html = generateHtml({ nodes: [], edges: [] }, mockMetrics as any);
+        expect(html).not.toContain('Session Crawl:');
+    });
+});

package/tests/lock/lockManager.test.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { LockManager } from '../../src/lock/lockManager.js';
+import { generateLockKey } from '../../src/lock/hashKey.js';
+import fs from 'node:fs/promises';
+import { existsSync, unlinkSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { isPidAlive } from '../../src/lock/pidCheck.js';
+
+// Mock fs and os
+vi.mock('node:fs/promises');
+vi.mock('node:fs');
+vi.mock('node:os');
+vi.mock('../../src/lock/pidCheck.js', () => ({
+  isPidAlive: vi.fn()
+}));
+
+describe('LockManager', () => {
+  const mockHomeDir = '/home/user';
+  const lockDir = path.join(mockHomeDir, '.crawlith', 'locks');
+  const command = 'test-command';
+  const target = 'http://example.com';
+  const options = { limit: 10 };
+  const lockHash = generateLockKey(command, target, options);
+  const lockPath = path.join(lockDir, `${lockHash}.lock`);
+
+  beforeEach(() => {
+    vi.resetAllMocks();
+    vi.mocked(os.homedir).mockReturnValue(mockHomeDir);
+    vi.mocked(fs.mkdir).mockResolvedValue(undefined);
+    vi.mocked(fs.writeFile).mockResolvedValue(undefined);
+    vi.mocked(existsSync).mockReturnValue(false);
+    vi.mocked(readFileSync).mockReturnValue('{}');
+    vi.mocked(unlinkSync).mockReturnValue(undefined);
+
+    // Mock process.pid
+    Object.defineProperty(process, 'pid', { value: 12345, configurable: true });
+
+    // Mock process.exit to throw error to stop execution flow in tests
+    vi.spyOn(process, 'exit').mockImplementation((code) => {
+      throw new Error(`Process exit ${code}`);
+    });
+
+    // Mock console to suppress noise
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    // Reset static state if any (LockManager stores lockFilePath)
+    // We can't easily reset private static via TS, but we can call releaseLock which clears it if set
+    LockManager.releaseLock();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('should acquire lock when no lock exists', async () => {
+    await LockManager.acquireLock(command, target, options);
+
+    expect(fs.mkdir).toHaveBeenCalledWith(lockDir, { recursive: true });
+    expect(fs.writeFile).toHaveBeenCalledWith(
+      lockPath,
+      expect.stringContaining('"limit": 10'),
+      expect.objectContaining({ flag: 'wx' })
+    );
+  });
+
+  it('should fail if lock exists and PID is alive', async () => {
+    vi.mocked(existsSync).mockReturnValue(true);
+    vi.mocked(readFileSync).mockReturnValue(JSON.stringify({
+      pid: 9999,
+      startedAt: Date.now(),
+      command,
+      target,
+      args: options
+    }));
+    vi.mocked(isPidAlive).mockReturnValue(true);
+
+    await expect(LockManager.acquireLock(command, target, options)).rejects.toThrow('Process exit 1');
+
+    expect(console.error).toHaveBeenCalledWith(expect.stringContaining('already running'));
+  });
+
+  it('should clear stale lock and acquire if PID is dead', async () => {
+    vi.mocked(existsSync).mockReturnValue(true);
+    vi.mocked(readFileSync).mockReturnValue(JSON.stringify({
+      pid: 9999,
+      startedAt: Date.now(),
+      command,
+      target,
+      args: options
+    }));
+    vi.mocked(isPidAlive).mockReturnValue(false);
+
+    await LockManager.acquireLock(command, target, options);
+
+    expect(unlinkSync).toHaveBeenCalledWith(lockPath);
+    expect(fs.writeFile).toHaveBeenCalled();
+    expect(console.log).toHaveBeenCalledWith(expect.stringContaining('Detected stale lock'));
+  });
+
+  it('should override lock if force is true', async () => {
+    vi.mocked(existsSync).mockReturnValue(true);
+    // Even if PID is alive
+    vi.mocked(readFileSync).mockReturnValue(JSON.stringify({
+      pid: 9999
+    }));
+    vi.mocked(isPidAlive).mockReturnValue(true);
+
+    await LockManager.acquireLock(command, target, options, true); // force = true
+
+    expect(unlinkSync).toHaveBeenCalledWith(lockPath);
+    expect(fs.writeFile).toHaveBeenCalled();
+    expect(console.warn).toHaveBeenCalledWith(expect.stringContaining('Force mode enabled'));
+  });
+
+  it('should handle race condition (EEXIST)', async () => {
+    vi.mocked(existsSync).mockReturnValue(false);
+    vi.mocked(fs.writeFile).mockRejectedValue({ code: 'EEXIST' });
+
+    await expect(LockManager.acquireLock(command, target, options)).rejects.toThrow('Process exit 1');
+    expect(console.error).toHaveBeenCalledWith(expect.stringContaining('Race condition'));
+  });
+
+  it('should release lock on exit', async () => {
+    // Acquire first (existsSync returns false by default from beforeEach)
+    await LockManager.acquireLock(command, target, options);
+
+    // Simulate file exists for release
+    vi.mocked(existsSync).mockReturnValue(true);
+
+    // Simulate release
+    LockManager.releaseLock();
+
+    expect(unlinkSync).toHaveBeenCalledWith(lockPath);
+  });
+});