@sylphx/flow 1.0.1 → 1.0.3

package/src/utils/file-operations.ts

@@ -0,0 +1,310 @@
+/**
+ * Standardized file operations utilities
+ * Provides consistent async file operations with proper error handling
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { pathSecurity } from './security.js';
+import { formatFileSize as formatFileSizeCore } from '../core/formatting/bytes.js';
+
+export interface FileReadOptions {
+  encoding?: BufferEncoding;
+  fallback?: string;
+}
+
+export interface FileWriteOptions {
+  encoding?: BufferEncoding;
+  createDir?: boolean;
+  backup?: boolean;
+}
+
+export interface FileCopyOptions {
+  overwrite?: boolean;
+  createDir?: boolean;
+}
+
+export interface FileInfo {
+  exists: boolean;
+  isFile: boolean;
+  isDirectory: boolean;
+  size?: number;
+  mtime?: Date;
+  atime?: Date;
+  ctime?: Date;
+}
+
+/**
+ * Safely read a file with encoding and fallback options
+ */
+export async function readFileSafe(
+  filePath: string,
+  options: FileReadOptions = {}
+): Promise<string | null> {
+  const { encoding = 'utf8', fallback } = options;
+
+  try {
+    const content = await fs.readFile(filePath, encoding);
+    return content;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT' && fallback !== undefined) {
+      return fallback;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Safely write a file with directory creation and backup options
+ */
+export async function writeFileSafe(
+  filePath: string,
+  content: string,
+  options: FileWriteOptions = {}
+): Promise<void> {
+  const { encoding = 'utf8', createDir = true, backup = false } = options;
+
+  // Validate path security
+  pathSecurity.validatePath(filePath);
+
+  // Create directory if needed
+  if (createDir) {
+    const dir = path.dirname(filePath);
+    await ensureDirectory(dir);
+  }
+
+  // Create backup if requested and file exists
+  if (backup && (await fileExists(filePath))) {
+    const backupPath = `${filePath}.backup.${Date.now()}`;
+    await fs.copyFile(filePath, backupPath);
+  }
+
+  await fs.writeFile(filePath, content, encoding);
+}
+
+/**
+ * Check if a file or directory exists
+ */
+export async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get comprehensive file information
+ */
+export async function getFileInfo(filePath: string): Promise<FileInfo> {
+  try {
+    const stats = await fs.stat(filePath);
+    return {
+      exists: true,
+      isFile: stats.isFile(),
+      isDirectory: stats.isDirectory(),
+      size: stats.size,
+      mtime: stats.mtime,
+      atime: stats.atime,
+      ctime: stats.ctime,
+    };
+  } catch {
+    return {
+      exists: false,
+      isFile: false,
+      isDirectory: false,
+    };
+  }
+}
+
+/**
+ * Ensure a directory exists, creating it if necessary
+ */
+export async function ensureDirectory(dirPath: string): Promise<void> {
+  try {
+    await fs.access(dirPath);
+  } catch {
+    await fs.mkdir(dirPath, { recursive: true });
+  }
+}
+
+/**
+ * Safely copy a file with options
+ */
+export async function copyFileSafe(
+  sourcePath: string,
+  destPath: string,
+  options: FileCopyOptions = {}
+): Promise<void> {
+  const { overwrite = false, createDir = true } = options;
+
+  // Validate path security
+  pathSecurity.validatePath(sourcePath);
+  pathSecurity.validatePath(destPath);
+
+  // Check if source exists
+  if (!(await fileExists(sourcePath))) {
+    throw new Error(`Source file does not exist: ${sourcePath}`);
+  }
+
+  // Check if destination exists and overwrite is false
+  if (!overwrite && (await fileExists(destPath))) {
+    throw new Error(`Destination file already exists: ${destPath}`);
+  }
+
+  // Create destination directory if needed
+  if (createDir) {
+    const destDir = path.dirname(destPath);
+    await ensureDirectory(destDir);
+  }
+
+  await fs.copyFile(sourcePath, destPath);
+}
+
+/**
+ * Safely delete a file or directory
+ */
+export async function deletePathSafe(targetPath: string): Promise<void> {
+  // Validate path security
+  pathSecurity.validatePath(targetPath);
+
+  if (!(await fileExists(targetPath))) {
+    return; // Already deleted
+  }
+
+  const info = await getFileInfo(targetPath);
+
+  if (info.isDirectory) {
+    await fs.rm(targetPath, { recursive: true, force: true });
+  } else {
+    await fs.unlink(targetPath);
+  }
+}
+
+/**
+ * Read directory contents safely
+ */
+export async function readDirectorySafe(
+  dirPath: string,
+  options: { recursive?: boolean; includeFiles?: boolean; includeDirectories?: boolean } = {}
+): Promise<string[]> {
+  const { recursive = false, includeFiles = true, includeDirectories = true } = options;
+
+  // Validate path security
+  pathSecurity.validatePath(dirPath);
+
+  if (!(await fileExists(dirPath))) {
+    throw new Error(`Directory does not exist: ${dirPath}`);
+  }
+
+  const info = await getFileInfo(dirPath);
+  if (!info.isDirectory) {
+    throw new Error(`Path is not a directory: ${dirPath}`);
+  }
+
+  if (recursive) {
+    const results: string[] = [];
+    const items = await fs.readdir(dirPath, { withFileTypes: true });
+
+    for (const item of items) {
+      const fullPath = path.join(dirPath, item.name);
+
+      if (item.isDirectory() && includeDirectories) {
+        results.push(fullPath);
+        const subResults = await readDirectorySafe(fullPath, options);
+        results.push(...subResults);
+      } else if (item.isFile() && includeFiles) {
+        results.push(fullPath);
+      }
+    }
+
+    return results;
+  }
+  const items = await fs.readdir(dirPath, { withFileTypes: true });
+  return items
+    .filter((item) => {
+      if (item.isFile() && includeFiles) {
+        return true;
+      }
+      if (item.isDirectory() && includeDirectories) {
+        return true;
+      }
+      return false;
+    })
+    .map((item) => path.join(dirPath, item.name));
+}
+
+/**
+ * Find files matching patterns in a directory
+ */
+export async function findFiles(
+  dirPath: string,
+  patterns: string[],
+  options: { recursive?: boolean; caseSensitive?: boolean } = {}
+): Promise<string[]> {
+  const { recursive = true, caseSensitive = true } = options;
+
+  const allFiles = await readDirectorySafe(dirPath, {
+    recursive,
+    includeFiles: true,
+    includeDirectories: false,
+  });
+
+  const regexPatterns = patterns.map((pattern) => {
+    const regexPattern = pattern.replace(/\./g, '\\.').replace(/\*/g, '.*').replace(/\?/g, '.');
+    return new RegExp(regexPattern, caseSensitive ? '' : 'i');
+  });
+
+  return allFiles.filter((filePath) => {
+    const fileName = path.basename(filePath);
+    return regexPatterns.some((regex) => regex.test(fileName));
+  });
+}
+
+/**
+ * Move a file safely with validation
+ */
+export async function moveFileSafe(
+  sourcePath: string,
+  destPath: string,
+  options: { overwrite?: boolean; createDir?: boolean } = {}
+): Promise<void> {
+  const { overwrite = false, createDir = true } = options;
+
+  // Copy first, then delete original
+  await copyFileSafe(sourcePath, destPath, { overwrite, createDir });
+  await deletePathSafe(sourcePath);
+}
+
+/**
+ * Get file size in human readable format
+ */
+export function formatFileSize(bytes: number): string {
+  return formatFileSizeCore(bytes);
+}
+
+/**
+ * Validate file path against security constraints
+ */
+export function validateFilePath(filePath: string, allowedBasePaths?: string[]): boolean {
+  try {
+    pathSecurity.validatePath(filePath);
+
+    if (allowedBasePaths) {
+      const resolved = path.resolve(filePath);
+      const isAllowed = allowedBasePaths.some((basePath) => {
+        const resolvedBase = path.resolve(basePath);
+        return resolved.startsWith(resolvedBase);
+      });
+
+      if (!isAllowed) {
+        return false;
+      }
+    }
+
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/utils/file-scanner.ts

@@ -0,0 +1,259 @@
+/**
+ * File Scanner
+ * Scan project files for @file auto-completion with caching
+ */
+
+import { readdir, stat, readFile as fsReadFile, writeFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+
+export interface FileInfo {
+  path: string;
+  relativePath: string;
+  size: number;
+}
+
+// Default ignore patterns
+const DEFAULT_IGNORE = [
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  '.next',
+  '.vercel',
+  '.turbo',
+  'coverage',
+  '.cache',
+  '.sylphx',
+  'bun.lock',
+  'package-lock.json',
+  'yarn.lock',
+];
+
+/**
+ * Load .gitignore patterns
+ */
+async function loadGitignore(rootPath: string): Promise<Set<string>> {
+  const patterns = new Set<string>(DEFAULT_IGNORE);
+
+  try {
+    const gitignorePath = join(rootPath, '.gitignore');
+    const content = await readFile(gitignorePath, 'utf8');
+
+    // Parse gitignore file
+    for (const line of content.split('\n')) {
+      const trimmed = line.trim();
+      // Skip empty lines and comments
+      if (trimmed && !trimmed.startsWith('#')) {
+        // Remove trailing slashes
+        const pattern = trimmed.endsWith('/') ? trimmed.slice(0, -1) : trimmed;
+        patterns.add(pattern);
+      }
+    }
+  } catch {
+    // No .gitignore file, use defaults only
+  }
+
+  return patterns;
+}
+
+/**
+ * Check if path should be ignored
+ */
+function shouldIgnore(relativePath: string, patterns: Set<string>): boolean {
+  // Check if any part of the path matches ignore patterns
+  const parts = relativePath.split('/');
+
+  for (const pattern of patterns) {
+    // Exact match
+    if (relativePath === pattern) return true;
+
+    // Directory match
+    if (parts.includes(pattern)) return true;
+
+    // Glob pattern (basic support for *)
+    if (pattern.includes('*')) {
+      const regex = new RegExp('^' + pattern.replace(/\*/g, '.*') + '$');
+      if (regex.test(relativePath)) return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Recursively scan directory for files (parallelized)
+ */
+async function scanDirectory(
+  dirPath: string,
+  rootPath: string,
+  patterns: Set<string>,
+  results: FileInfo[] = []
+): Promise<FileInfo[]> {
+  try {
+    const entries = await readdir(dirPath, { withFileTypes: true });
+
+    // Separate files and directories for parallel processing
+    const files: typeof entries = [];
+    const directories: typeof entries = [];
+
+    for (const entry of entries) {
+      const fullPath = join(dirPath, entry.name);
+      const relativePath = relative(rootPath, fullPath);
+
+      // Skip ignored paths
+      if (shouldIgnore(relativePath, patterns)) {
+        continue;
+      }
+
+      if (entry.isDirectory()) {
+        directories.push(entry);
+      } else if (entry.isFile()) {
+        files.push(entry);
+      }
+    }
+
+    // Process files in parallel (no need to stat each one individually)
+    // Use entry.isFile() which we already know, skip stat() call for performance
+    const fileResults = files.map((entry) => {
+      const fullPath = join(dirPath, entry.name);
+      const relativePath = relative(rootPath, fullPath);
+      return {
+        path: fullPath,
+        relativePath,
+        size: 0, // We skip stat() for performance, size not critical for autocomplete
+      };
+    });
+    results.push(...fileResults);
+
+    // Process subdirectories in parallel
+    if (directories.length > 0) {
+      const subdirResults = await Promise.all(
+        directories.map((entry) => {
+          const fullPath = join(dirPath, entry.name);
+          return scanDirectory(fullPath, rootPath, patterns, []);
+        })
+      );
+
+      // Flatten results from all subdirectories
+      for (const subdirResult of subdirResults) {
+        results.push(...subdirResult);
+      }
+    }
+  } catch (error) {
+    // Skip directories we can't read
+  }
+
+  return results;
+}
+
+// Cache for scanned files
+const CACHE_DIR = join(homedir(), '.sylphx', 'cache');
+const CACHE_VERSION = 1;
+
+interface ScanCache {
+  version: number;
+  rootPath: string;
+  timestamp: number;
+  files: FileInfo[];
+}
+
+/**
+ * Get cache file path for a project
+ */
+function getCachePath(rootPath: string): string {
+  // Use hash of root path as cache filename
+  const hash = Buffer.from(rootPath).toString('base64').replace(/[/+=]/g, '_');
+  return join(CACHE_DIR, `filescan-${hash}.json`);
+}
+
+/**
+ * Load cached file list if valid
+ */
+async function loadCache(rootPath: string): Promise<FileInfo[] | null> {
+  try {
+    const cachePath = getCachePath(rootPath);
+    const content = await fsReadFile(cachePath, 'utf8');
+    const cache: ScanCache = JSON.parse(content);
+
+    // Validate cache
+    if (cache.version !== CACHE_VERSION || cache.rootPath !== rootPath) {
+      return null;
+    }
+
+    // Check if cache is still fresh (less than 5 minutes old)
+    const age = Date.now() - cache.timestamp;
+    const MAX_CACHE_AGE = 5 * 60 * 1000; // 5 minutes
+    if (age > MAX_CACHE_AGE) {
+      return null;
+    }
+
+    return cache.files;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save file list to cache
+ */
+async function saveCache(rootPath: string, files: FileInfo[]): Promise<void> {
+  try {
+    const cachePath = getCachePath(rootPath);
+    const cache: ScanCache = {
+      version: CACHE_VERSION,
+      rootPath,
+      timestamp: Date.now(),
+      files,
+    };
+
+    // Ensure cache directory exists
+    const { mkdir } = await import('node:fs/promises');
+    await mkdir(CACHE_DIR, { recursive: true });
+
+    // Write cache file
+    await writeFile(cachePath, JSON.stringify(cache), 'utf8');
+  } catch (error) {
+    // Ignore cache write errors
+    console.warn('Failed to write file scanner cache:', error);
+  }
+}
+
+/**
+ * Scan project files with caching
+ * Returns list of files respecting .gitignore
+ */
+export async function scanProjectFiles(rootPath: string): Promise<FileInfo[]> {
+  // Try to load from cache first
+  const cached = await loadCache(rootPath);
+  if (cached) {
+    return cached;
+  }
+
+  // Cache miss or stale, scan filesystem
+  const patterns = await loadGitignore(rootPath);
+  const files = await scanDirectory(rootPath, rootPath, patterns);
+
+  // Sort by path for consistent ordering
+  files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+
+  // Save to cache for next time
+  saveCache(rootPath, files).catch(() => {
+    // Ignore cache save errors
+  });
+
+  return files;
+}
+
+/**
+ * Filter files by query string
+ */
+export function filterFiles(files: FileInfo[], query: string): FileInfo[] {
+  if (!query) return files;
+
+  const lowerQuery = query.toLowerCase();
+  return files.filter((file) =>
+    file.relativePath.toLowerCase().includes(lowerQuery)
+  );
+}