tidyf 1.0.0

package/src/lib/watcher.ts

@@ -0,0 +1,151 @@
+/**
+ * File watcher for tidy
+ *
+ * Uses chokidar to watch directories for new files and emits batched events
+ */
+
+import chokidar from "chokidar";
+import { EventEmitter } from "events";
+import type { WatchEvent } from "../types/organizer.ts";
+
+/**
+ * Options for the file watcher
+ */
+export interface WatcherOptions {
+  /** Debounce delay in milliseconds */
+  delay?: number;
+  /** Patterns to ignore */
+  ignore?: string[];
+  /** Whether to watch subdirectories */
+  recursive?: boolean;
+}
+
+/**
+ * File watcher that batches events and emits after debounce
+ */
+export class FileWatcher extends EventEmitter {
+  private watcher: chokidar.FSWatcher | null = null;
+  private debounceTimer: NodeJS.Timeout | null = null;
+  private pendingFiles: Map<string, WatchEvent> = new Map();
+  private isRunning = false;
+
+  constructor(private options: WatcherOptions = {}) {
+    super();
+    this.options.delay = this.options.delay ?? 3000;
+  }
+
+  /**
+   * Start watching the specified paths
+   */
+  start(paths: string[]): void {
+    if (this.isRunning) {
+      return;
+    }
+
+    this.isRunning = true;
+
+    // Build ignore patterns for chokidar
+    const ignored = [
+      /(^|[\/\\])\../, // Hidden files
+      "**/node_modules/**",
+      "**/.git/**",
+      ...(this.options.ignore || []),
+    ];
+
+    this.watcher = chokidar.watch(paths, {
+      persistent: true,
+      ignoreInitial: true,
+      ignored,
+      depth: this.options.recursive ? undefined : 0,
+      awaitWriteFinish: {
+        stabilityThreshold: 2000,
+        pollInterval: 100,
+      },
+    });
+
+    this.watcher.on("add", (path) => this.handleEvent("add", path));
+    this.watcher.on("change", (path) => this.handleEvent("change", path));
+    this.watcher.on("error", (error) => this.emit("error", error));
+
+    this.watcher.on("ready", () => {
+      this.emit("ready", paths);
+    });
+  }
+
+  /**
+   * Handle a file event
+   */
+  private handleEvent(type: "add" | "change", path: string): void {
+    // Add to pending files
+    this.pendingFiles.set(path, {
+      type,
+      path,
+      timestamp: new Date(),
+    });
+
+    // Reset debounce timer
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+    }
+
+    this.debounceTimer = setTimeout(() => {
+      this.flushPendingFiles();
+    }, this.options.delay);
+  }
+
+  /**
+   * Flush pending files and emit batch event
+   */
+  private flushPendingFiles(): void {
+    if (this.pendingFiles.size === 0) {
+      return;
+    }
+
+    const files = Array.from(this.pendingFiles.values());
+    this.pendingFiles.clear();
+
+    this.emit("files", files);
+  }
+
+  /**
+   * Stop watching
+   */
+  stop(): void {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+
+    // Flush any remaining files
+    this.flushPendingFiles();
+
+    if (this.watcher) {
+      this.watcher.close();
+      this.watcher = null;
+    }
+
+    this.isRunning = false;
+    this.emit("stop");
+  }
+
+  /**
+   * Check if watcher is running
+   */
+  get running(): boolean {
+    return this.isRunning;
+  }
+
+  /**
+   * Get number of pending files
+   */
+  get pendingCount(): number {
+    return this.pendingFiles.size;
+  }
+}
+
+/**
+ * Create a new file watcher
+ */
+export function createWatcher(options?: WatcherOptions): FileWatcher {
+  return new FileWatcher(options);
+}

package/src/types/config.ts

@@ -0,0 +1,69 @@
+/**
+ * Configuration types for tidy
+ */
+
+/**
+ * Model selection for AI operations
+ */
+export interface ModelSelection {
+	provider: string;
+	model: string;
+}
+
+/**
+ * Folder rule configuration
+ */
+export interface FolderRule {
+	/** Source folder patterns (glob or paths) */
+	sources: string[];
+	/** Target base directory */
+	target: string;
+	/** Whether to watch this folder */
+	watch?: boolean;
+}
+
+/**
+ * Category rule for organizing files
+ */
+export interface CategoryRule {
+	/** Category name */
+	name: string;
+	/** File extensions that belong to this category */
+	extensions?: string[];
+	/** MIME type patterns */
+	mimeTypes?: string[];
+	/** Subfolder name */
+	subfolder: string;
+}
+
+/**
+ * Main configuration interface
+ */
+export interface TidyConfig {
+	/** Model for file analysis */
+	organizer?: ModelSelection;
+	/** Default source directory */
+	defaultSource?: string;
+	/** Default target directory */
+	defaultTarget?: string;
+	/** Whether watch mode is enabled by default */
+	watchEnabled?: boolean;
+	/** Folder rules */
+	folders?: FolderRule[];
+	/** Category rules (hints for AI) */
+	categories?: CategoryRule[];
+	/** Files/patterns to ignore */
+	ignore?: string[];
+	/** Whether to read file content for better categorization */
+	readContent?: boolean;
+	/** Max file size to read content (in bytes) */
+	maxContentSize?: number;
+}
+
+/**
+ * Options for config command
+ */
+export interface ConfigOptions {
+	/** Whether to configure locally (current directory) */
+	local?: boolean;
+}

package/src/types/organizer.ts

@@ -0,0 +1,144 @@
+/**
+ * Core types for the file organizer
+ */
+
+/**
+ * Metadata about a file to be organized
+ */
+export interface FileMetadata {
+  /** Full path to the file */
+  path: string;
+  /** File name without path */
+  name: string;
+  /** File extension (without dot) */
+  extension: string;
+  /** File size in bytes */
+  size: number;
+  /** Last modified timestamp */
+  modifiedAt: Date;
+  /** Created timestamp */
+  createdAt: Date;
+  /** MIME type if detectable */
+  mimeType?: string;
+  /** Optional content preview (first N bytes/lines) */
+  contentPreview?: string;
+}
+
+/**
+ * AI-suggested category for a file
+ */
+export interface FileCategory {
+  /** Category name (e.g., "Documents", "Images", "Projects") */
+  name: string;
+  /** Subcategory if applicable (e.g., "Work", "Personal") */
+  subcategory?: string;
+  /** Suggested subfolder path relative to target */
+  suggestedPath: string;
+  /** Confidence score 0-1 */
+  confidence: number;
+  /** AI's reasoning for this categorization */
+  reasoning: string;
+}
+
+/**
+ * A proposed file move operation
+ */
+export interface FileMoveProposal {
+  /** Original file path */
+  sourcePath: string;
+  /** Source file metadata */
+  file: FileMetadata;
+  /** Proposed destination path (full path) */
+  destination: string;
+  /** Category information */
+  category: FileCategory;
+  /** Whether file already exists at destination */
+  conflictExists: boolean;
+}
+
+/**
+ * Result of AI analysis
+ */
+export interface OrganizationProposal {
+  /** List of proposed moves */
+  proposals: FileMoveProposal[];
+  /** Overall strategy explanation */
+  strategy: string;
+  /** Files that couldn't be categorized */
+  uncategorized: FileMetadata[];
+  /** Timestamp of analysis */
+  analyzedAt: Date;
+}
+
+/**
+ * Options for organize command
+ */
+export interface OrganizeOptions {
+  /** Directory to scan */
+  path?: string;
+  /** Preview without executing */
+  dryRun?: boolean;
+  /** Skip confirmations */
+  yes?: boolean;
+  /** Scan subdirectories */
+  recursive?: boolean;
+  /** Max depth for recursive scan */
+  depth?: string;
+  /** Target directory for organized files */
+  target?: string;
+  /** Model override */
+  model?: string;
+}
+
+/**
+ * Options for watch command
+ */
+export interface WatchOptions {
+  /** Directories to watch */
+  paths?: string[];
+  /** Debounce delay in ms */
+  delay?: string;
+  /** Auto-apply without confirmation */
+  auto?: boolean;
+  /** Queue for review instead of auto-apply */
+  queue?: boolean;
+  /** Model override */
+  model?: string;
+}
+
+/**
+ * Watch event for a new file
+ */
+export interface WatchEvent {
+  /** Event type */
+  type: "add" | "change";
+  /** File path */
+  path: string;
+  /** Timestamp */
+  timestamp: Date;
+}
+
+/**
+ * Status of a file move operation
+ */
+export type MoveStatus =
+  | "pending"
+  | "moving"
+  | "completed"
+  | "failed"
+  | "skipped"
+  | "conflict";
+
+/**
+ * Result of a file move operation
+ */
+export interface MoveResult {
+  /** Source path */
+  source: string;
+  /** Destination path */
+  destination: string;
+  /** Move status */
+  status: MoveStatus;
+  /** Error message if failed */
+  error?: string;
+}

package/src/utils/files.ts

@@ -0,0 +1,198 @@
+/**
+ * File system utilities for tidy
+ */
+
+import { rename, mkdir, access, copyFile, unlink, stat } from "fs/promises";
+import { dirname, join, basename, extname } from "path";
+import { existsSync } from "fs";
+import type { MoveResult, MoveStatus } from "../types/organizer.ts";
+
+/**
+ * Check if a file exists
+ */
+export async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Ensure a directory exists, creating it if necessary
+ */
+export async function ensureDirectory(dirPath: string): Promise<void> {
+  if (!existsSync(dirPath)) {
+    await mkdir(dirPath, { recursive: true });
+  }
+}
+
+/**
+ * Generate a unique filename by appending a number if the file already exists
+ */
+export async function generateUniqueName(
+  destination: string
+): Promise<string> {
+  if (!(await fileExists(destination))) {
+    return destination;
+  }
+
+  const dir = dirname(destination);
+  const ext = extname(destination);
+  const base = basename(destination, ext);
+
+  let counter = 1;
+  let newPath: string;
+
+  do {
+    newPath = join(dir, `${base} (${counter})${ext}`);
+    counter++;
+  } while (await fileExists(newPath));
+
+  return newPath;
+}
+
+/**
+ * Conflict resolution strategy
+ */
+export type ConflictStrategy = "rename" | "overwrite" | "skip";
+
+/**
+ * Resolve a destination path conflict
+ */
+export async function resolveConflict(
+  destination: string,
+  strategy: ConflictStrategy
+): Promise<{ path: string; status: MoveStatus }> {
+  const exists = await fileExists(destination);
+
+  if (!exists) {
+    return { path: destination, status: "pending" };
+  }
+
+  switch (strategy) {
+    case "rename":
+      return { path: await generateUniqueName(destination), status: "pending" };
+    case "overwrite":
+      return { path: destination, status: "pending" };
+    case "skip":
+      return { path: destination, status: "skipped" };
+    default:
+      return { path: destination, status: "conflict" };
+  }
+}
+
+/**
+ * Move a file from source to destination
+ */
+export async function moveFile(
+  source: string,
+  destination: string,
+  options: {
+    overwrite?: boolean;
+    backup?: boolean;
+  } = {}
+): Promise<MoveResult> {
+  try {
+    // Ensure the destination directory exists
+    await ensureDirectory(dirname(destination));
+
+    // Check if destination exists
+    const destExists = await fileExists(destination);
+
+    if (destExists) {
+      if (options.backup) {
+        // Create a backup of the existing file
+        const backupPath = await generateUniqueName(destination + ".backup");
+        await copyFile(destination, backupPath);
+      }
+
+      if (!options.overwrite) {
+        // Generate a unique name
+        destination = await generateUniqueName(destination);
+      }
+    }
+
+    // Try to rename (move) the file
+    try {
+      await rename(source, destination);
+    } catch (error: any) {
+      // If rename fails (cross-device), fall back to copy + delete
+      if (error.code === "EXDEV") {
+        await copyFile(source, destination);
+        await unlink(source);
+      } else {
+        throw error;
+      }
+    }
+
+    return {
+      source,
+      destination,
+      status: "completed",
+    };
+  } catch (error: any) {
+    return {
+      source,
+      destination,
+      status: "failed",
+      error: error.message,
+    };
+  }
+}
+
+/**
+ * Get file stats safely
+ */
+export async function getFileStats(
+  filePath: string
+): Promise<{ size: number; mtime: Date; birthtime: Date } | null> {
+  try {
+    const stats = await stat(filePath);
+    return {
+      size: stats.size,
+      mtime: stats.mtime,
+      birthtime: stats.birthtime,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Format file size for display
+ */
+export function formatFileSize(bytes: number): string {
+  if (bytes === 0) return "0 B";
+
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  const k = 1024;
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+
+  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(1))} ${units[i]}`;
+}
+
+/**
+ * Check if a path is a directory
+ */
+export async function isDirectory(path: string): Promise<boolean> {
+  try {
+    const stats = await stat(path);
+    return stats.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a path is a file
+ */
+export async function isFile(path: string): Promise<boolean> {
+  try {
+    const stats = await stat(path);
+    return stats.isFile();
+  } catch {
+    return false;
+  }
+}