@sooink/ai-session-tidy 0.1.1

package/src/core/watcher.test.ts

@@ -0,0 +1,210 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import { mkdir, rm, writeFile } from 'fs/promises';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+import { Watcher, WatcherOptions, WatchEvent } from './watcher.js';
+
+describe('Watcher', () => {
+  const testDir = join(tmpdir(), 'watchertest' + Date.now());
+
+  beforeEach(async () => {
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  describe('watch', () => {
+    it('detects project folder deletion', async () => {
+      const projectDir = join(testDir, 'myproject');
+      await mkdir(projectDir);
+
+      const allEvents: WatchEvent[] = [];
+      const watcher = new Watcher({
+        watchPaths: [testDir],
+        delayMs: 50, // Short delay for testing
+        debounceMs: 50, // Short debounce for testing
+        onDelete: (events) => allEvents.push(...events),
+      });
+
+      watcher.start();
+
+      // Wait for watcher initialization
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      // Delete project
+      await rm(projectDir, { recursive: true });
+
+      // Wait for event detection (delay + debounce)
+      await new Promise((resolve) => setTimeout(resolve, 300));
+
+      watcher.stop();
+
+      expect(allEvents.length).toBeGreaterThanOrEqual(1);
+      expect(allEvents[0].path).toContain('myproject');
+    });
+
+    it('executes cleanup after delay', async () => {
+      const projectDir = join(testDir, 'delayproject');
+      await mkdir(projectDir);
+
+      let cleanupCalled = false;
+      const watcher = new Watcher({
+        watchPaths: [testDir],
+        delayMs: 100,
+        debounceMs: 50,
+        onDelete: () => {
+          cleanupCalled = true;
+        },
+      });
+
+      watcher.start();
+
+      // Wait for watcher initialization
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      await rm(projectDir, { recursive: true });
+
+      // Not called before delay
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      expect(cleanupCalled).toBe(false);
+
+      // Called after delay + debounce
+      await new Promise((resolve) => setTimeout(resolve, 200));
+      expect(cleanupCalled).toBe(true);
+
+      watcher.stop();
+    });
+
+    it('cancels cleanup if recovered during delay', async () => {
+      const projectDir = join(testDir, 'recoveryproject');
+      await mkdir(projectDir);
+
+      let cleanupCalled = false;
+      const watcher = new Watcher({
+        watchPaths: [testDir],
+        delayMs: 200,
+        debounceMs: 50,
+        onDelete: () => {
+          cleanupCalled = true;
+        },
+      });
+
+      watcher.start();
+
+      // Wait for watcher initialization
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      // Delete then immediately recover
+      await rm(projectDir, { recursive: true });
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      await mkdir(projectDir);
+
+      // Not called even after delay + debounce
+      await new Promise((resolve) => setTimeout(resolve, 300));
+      expect(cleanupCalled).toBe(false);
+
+      watcher.stop();
+    });
+
+    it('does not detect events after stop', async () => {
+      const projectDir = join(testDir, 'stoptest');
+      await mkdir(projectDir);
+
+      const allEvents: WatchEvent[] = [];
+      const watcher = new Watcher({
+        watchPaths: [testDir],
+        delayMs: 50,
+        debounceMs: 50,
+        onDelete: (events) => allEvents.push(...events),
+      });
+
+      watcher.start();
+      // Wait for watcher initialization then stop
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      watcher.stop();
+
+      await rm(projectDir, { recursive: true });
+      await new Promise((resolve) => setTimeout(resolve, 200));
+
+      expect(allEvents).toHaveLength(0);
+    });
+
+    it('debounces multiple folder deletions', async () => {
+      const dir1 = join(testDir, 'project1');
+      const dir2 = join(testDir, 'project2');
+      await mkdir(dir1);
+      await mkdir(dir2);
+
+      let callCount = 0;
+      let receivedEvents: WatchEvent[] = [];
+      const watcher = new Watcher({
+        watchPaths: [testDir],
+        delayMs: 50,
+        debounceMs: 100, // Debounce window
+        onDelete: (events) => {
+          callCount++;
+          receivedEvents = events;
+        },
+      });
+
+      watcher.start();
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      // Delete two folders consecutively
+      await rm(dir1, { recursive: true });
+      await rm(dir2, { recursive: true });
+
+      // Wait for delay + debounce
+      await new Promise((resolve) => setTimeout(resolve, 300));
+
+      watcher.stop();
+
+      // Should be called only once
+      expect(callCount).toBe(1);
+      // Two events delivered as a batch
+      expect(receivedEvents.length).toBe(2);
+    });
+  });
+
+  describe('isWatching', () => {
+    it('returns false before start', () => {
+      const watcher = new Watcher({
+        watchPaths: [testDir],
+        delayMs: 100,
+        debounceMs: 50,
+        onDelete: () => {},
+      });
+
+      expect(watcher.isWatching()).toBe(false);
+    });
+
+    it('returns true after start', () => {
+      const watcher = new Watcher({
+        watchPaths: [testDir],
+        delayMs: 100,
+        debounceMs: 50,
+        onDelete: () => {},
+      });
+
+      watcher.start();
+      expect(watcher.isWatching()).toBe(true);
+      watcher.stop();
+    });
+
+    it('returns false after stop', () => {
+      const watcher = new Watcher({
+        watchPaths: [testDir],
+        delayMs: 100,
+        debounceMs: 50,
+        onDelete: () => {},
+      });
+
+      watcher.start();
+      watcher.stop();
+      expect(watcher.isWatching()).toBe(false);
+    });
+  });
+});

package/src/core/watcher.ts

@@ -0,0 +1,194 @@
+import { watch, FSWatcher } from 'chokidar';
+import { access } from 'fs/promises';
+
+export interface WatchEvent {
+  path: string;
+  timestamp: Date;
+}
+
+export interface WatcherOptions {
+  watchPaths: string[];
+  /** Delay before cleanup after deletion detected (allows recovery) */
+  delayMs: number;
+  /** Debounce time to batch multiple delete events (default: 10 seconds) */
+  debounceMs?: number;
+  depth?: number;
+  /** Callback to handle batched delete events */
+  onDelete: (events: WatchEvent[]) => void;
+}
+
+/**
+ * Watcher that monitors project folder deletions and invokes cleanup callback
+ *
+ * ## Event Processing Flow
+ *
+ * When a folder is deleted, the OS generates individual events for each subfolder:
+ * ```
+ * rm -rf /project
+ *   → unlinkDir: /project/frontend
+ *   → unlinkDir: /project/backend
+ *   → unlinkDir: /project
+ * ```
+ *
+ * Running scan/cleanup for each event would be inefficient,
+ * so we use a two-stage delay mechanism:
+ *
+ * 1. **Per-path delay (delayMs)**: Provides recovery opportunity (default 5 min)
+ *    - If folder is restored during delay, cleanup is cancelled
+ *
+ * 2. **Debounce (debounceMs)**: Batches multiple events together (default 10 sec)
+ *    - After 10 seconds with no new events, batch is executed
+ *    - Scan/cleanup runs only once
+ *
+ * ## Timeline Example
+ *
+ * ```
+ * T+0s:      /project/frontend deletion detected → 5min timer starts
+ * T+0.1s:    /project/backend deletion detected → 5min timer starts
+ * T+0.2s:    /project deletion detected → 5min timer starts
+ * T+5m:      /project/frontend timer complete → add to batch, 10sec debounce starts
+ * T+5m0.1s:  /project/backend timer complete → add to batch, debounce reset
+ * T+5m0.2s:  /project timer complete → add to batch, debounce reset
+ * T+5m10.2s: debounce complete → onDelete([3 events]) → single scan execution
+ * ```
+ */
+export class Watcher {
+  private readonly options: WatcherOptions;
+  private readonly debounceMs: number;
+  private watcher: FSWatcher | null = null;
+  /** Per-path delay timers */
+  private pendingDeletes: Map<string, NodeJS.Timeout> = new Map();
+  /** Events waiting for debounce */
+  private batchedEvents: WatchEvent[] = [];
+  /** Debounce timer */
+  private debounceTimer: NodeJS.Timeout | null = null;
+
+  constructor(options: WatcherOptions) {
+    this.options = options;
+    this.debounceMs = options.debounceMs ?? 10000; // default 10 seconds
+  }
+
+  start(): void {
+    if (this.watcher) return;
+
+    this.watcher = watch(this.options.watchPaths, {
+      ignoreInitial: true,
+      persistent: true,
+      depth: this.options.depth ?? 3,
+    });
+
+    this.watcher.on('unlinkDir', (path) => {
+      this.handleDelete(path);
+    });
+
+    this.watcher.on('addDir', (path) => {
+      this.handleRecovery(path);
+    });
+  }
+
+  stop(): void {
+    if (!this.watcher) return;
+
+    this.watcher.close();
+    this.watcher = null;
+
+    // Cancel all pending timers
+    for (const timeout of this.pendingDeletes.values()) {
+      clearTimeout(timeout);
+    }
+    this.pendingDeletes.clear();
+
+    // Cancel debounce timer
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+    this.batchedEvents = [];
+  }
+
+  isWatching(): boolean {
+    return this.watcher !== null;
+  }
+
+  /**
+   * Handle folder deletion event
+   *
+   * Stage 1: Set per-path delay timer
+   * - Don't process immediately to allow recovery
+   * - Add to batch if still deleted after delay
+   */
+  private handleDelete(path: string): void {
+    // Ignore if already pending (prevent duplicate events)
+    if (this.pendingDeletes.has(path)) return;
+
+    const timeout = setTimeout(async () => {
+      // Verify path is still deleted after delay
+      const stillDeleted = !(await this.pathExists(path));
+
+      if (stillDeleted) {
+        // Move to stage 2: add to batch
+        this.addToBatch({
+          path,
+          timestamp: new Date(),
+        });
+      }
+
+      this.pendingDeletes.delete(path);
+    }, this.options.delayMs);
+
+    this.pendingDeletes.set(path, timeout);
+  }
+
+  /**
+   * Add event to batch and reset debounce timer
+   *
+   * Stage 2: Debounce
+   * - Reset timer on each new event
+   * - Execute batch when no new events for debounce period
+   * - This combines multiple subfolder deletions into single cleanup
+   */
+  private addToBatch(event: WatchEvent): void {
+    this.batchedEvents.push(event);
+
+    // Reset debounce timer (extend wait time on new event)
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+    }
+
+    this.debounceTimer = setTimeout(() => {
+      this.flushBatch();
+    }, this.debounceMs);
+  }
+
+  /**
+   * Deliver batched events to callback
+   * - Scan/cleanup runs only once
+   */
+  private flushBatch(): void {
+    if (this.batchedEvents.length === 0) return;
+
+    const events = [...this.batchedEvents];
+    this.batchedEvents = [];
+    this.debounceTimer = null;
+
+    this.options.onDelete(events);
+  }
+
+  private handleRecovery(path: string): void {
+    const timeout = this.pendingDeletes.get(path);
+
+    if (timeout) {
+      clearTimeout(timeout);
+      this.pendingDeletes.delete(path);
+    }
+  }
+
+  private async pathExists(path: string): Promise<boolean> {
+    try {
+      await access(path);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { cli } from './cli.js';
+
+cli.parse(process.argv);

package/src/scanners/claude-code.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import { mkdir, writeFile, rm } from 'fs/promises';
+import { join } from 'path';
+import { tmpdir, homedir } from 'os';
+
+import { ClaudeCodeScanner } from './claude-code.js';
+
+describe('ClaudeCodeScanner', () => {
+  const testBaseDir = join(tmpdir(), 'claudetest' + Date.now());
+  const mockProjectsDir = join(testBaseDir, '.claude', 'projects');
+
+  beforeEach(async () => {
+    await mkdir(mockProjectsDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testBaseDir, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  describe('isAvailable', () => {
+    it('returns true when projects directory exists', async () => {
+      const scanner = new ClaudeCodeScanner(mockProjectsDir);
+      expect(await scanner.isAvailable()).toBe(true);
+    });
+
+    it('returns false when directory does not exist', async () => {
+      const scanner = new ClaudeCodeScanner('/nonexistent/path/12345');
+      expect(await scanner.isAvailable()).toBe(false);
+    });
+  });
+
+  describe('scan', () => {
+    it('detects orphaned sessions (original project deleted)', async () => {
+      // Create encoded session directory: /deleted/project → -deleted-project
+      const sessionDir = join(mockProjectsDir, '-deleted-project');
+      await mkdir(sessionDir, { recursive: true });
+      await writeFile(join(sessionDir, 'session.json'), '{"test": true}');
+
+      const scanner = new ClaudeCodeScanner(mockProjectsDir);
+      const result = await scanner.scan();
+
+      expect(result.sessions).toHaveLength(1);
+      expect(result.sessions[0].projectPath).toBe('/deleted/project');
+      expect(result.sessions[0].sessionPath).toBe(sessionDir);
+      expect(result.sessions[0].toolName).toBe('claude-code');
+    });
+
+    it('excludes active projects (original exists)', async () => {
+      // Create actually existing directory (path without hyphens)
+      const realProjectDir = join(testBaseDir, 'existingproject');
+      await mkdir(realProjectDir, { recursive: true });
+
+      // Create session for that path
+      const encodedPath = realProjectDir.replace(/\//g, '-');
+      const sessionDir = join(mockProjectsDir, encodedPath);
+      await mkdir(sessionDir, { recursive: true });
+      await writeFile(join(sessionDir, 'session.json'), '{}');
+
+      const scanner = new ClaudeCodeScanner(mockProjectsDir);
+      const result = await scanner.scan();
+
+      // Sessions of existing projects are not orphaned
+      expect(result.sessions).toHaveLength(0);
+    });
+
+    it('calculates session size', async () => {
+      const sessionDir = join(mockProjectsDir, '-orphan-project');
+      await mkdir(sessionDir, { recursive: true });
+      await writeFile(join(sessionDir, 'data1.json'), 'a'.repeat(100));
+      await writeFile(join(sessionDir, 'data2.json'), 'b'.repeat(200));
+
+      const scanner = new ClaudeCodeScanner(mockProjectsDir);
+      const result = await scanner.scan();
+
+      expect(result.sessions[0].size).toBe(300);
+      expect(result.totalSize).toBe(300);
+    });
+
+    it('returns last modified time', async () => {
+      const sessionDir = join(mockProjectsDir, '-test-project');
+      await mkdir(sessionDir, { recursive: true });
+      await writeFile(join(sessionDir, 'file.json'), '{}');
+
+      const scanner = new ClaudeCodeScanner(mockProjectsDir);
+      const result = await scanner.scan();
+
+      expect(result.sessions[0].lastModified).toBeInstanceOf(Date);
+      // Should be within 1 minute since recently created
+      const timeDiff = Date.now() - result.sessions[0].lastModified.getTime();
+      expect(timeDiff).toBeLessThan(60000);
+    });
+
+    it('excludes empty directories from session list', async () => {
+      const sessionDir = join(mockProjectsDir, '-empty-project');
+      await mkdir(sessionDir, { recursive: true });
+
+      const scanner = new ClaudeCodeScanner(mockProjectsDir);
+      const result = await scanner.scan();
+
+      expect(result.sessions).toHaveLength(0);
+    });
+
+    it('records scan duration', async () => {
+      const scanner = new ClaudeCodeScanner(mockProjectsDir);
+      const result = await scanner.scan();
+
+      expect(result.scanDuration).toBeGreaterThanOrEqual(0);
+      expect(result.toolName).toBe('claude-code');
+    });
+  });
+});