Filesystem Tools

interface GluegunFilesystem {
  /** Operating system end-of-line marker (os.EOL) */
  eol: string;
  /** Path separator for current OS (path.sep) */
  separator: string;
  /** Get user home directory function (os.homedir) */
  homedir(): string;
  /** Change file permissions synchronously */
  chmodSync: typeof import('fs').chmodSync;
  /** Resolve path segments to absolute path */
  resolve: typeof import('path').resolve;

  /**
   * Get subdirectories of a path
   * @param path - Directory path to scan
   * @param isRelative - Return relative paths instead of absolute
   * @param matching - Glob pattern to filter directory names
   * @returns Array of subdirectory paths
   */
  subdirectories(path: string, isRelative?: boolean, matching?: string): string[];

  /**
   * Check if path is a file
   * @param path - Path to check
   * @returns True if path exists and is a file
   */
  isFile(path: string): boolean;

  /**
   * Check if path is not a file
   * @param path - Path to check
   * @returns True if path doesn't exist or is not a file
   */
  isNotFile(path: string): boolean;

  /**
   * Check if path is a directory
   * @param path - Path to check
   * @returns True if path exists and is a directory
   */
  isDirectory(path: string): boolean;

  /**
   * Check if path is not a directory
   * @param path - Path to check
   * @returns True if path doesn't exist or is not a directory
   */
  isNotDirectory(path: string): boolean;

  // All fs-jetpack methods are also available:
  
  /**
   * Read file contents
   * @param path - File path
   * @param returnAs - Return format ('utf8', 'buffer', 'json', 'jsonWithDates')
   * @returns File contents in specified format
   */
  read(path: string, returnAs?: 'utf8' | 'buffer' | 'json' | 'jsonWithDates'): string | Buffer | object | null;

  /**
   * Write content to file
   * @param path - File path
   * @param data - Content to write
   * @param options - Write options
   * @returns Path of written file
   */
  write(path: string, data: string | Buffer | object, options?: any): string;

  /**
   * Check if path exists
   * @param path - Path to check
   * @returns 'file', 'dir', or false
   */
  exists(path: string): 'file' | 'dir' | false;

  /**
   * Copy file or directory
   * @param from - Source path
   * @param to - Destination path
   * @param options - Copy options
   */
  copy(from: string, to: string, options?: any): void;

  /**
   * Move/rename file or directory
   * @param from - Source path
   * @param to - Destination path
   */
  move(from: string, to: string): void;

  /**
   * Remove file or directory
   * @param path - Path to remove
   */
  remove(path: string): void;

  /**
   * Find files matching criteria
   * @param path - Search path
   * @param searchCriteria - Search options
   * @returns Array of matching file paths
   */
  find(path: string, searchCriteria?: any): string[];

  /**
   * List directory contents
   * @param path - Directory path
   * @returns Array of file/directory names
   */
  list(path: string): string[];

  /**
   * Get directory tree structure
   * @param path - Directory path
   * @returns Tree object representation
   */
  tree(path: string): any;

  /**
   * Create directory
   * @param path - Directory path to create
   */
  dir(path: string): void;

  /**
   * Get file/directory info
   * @param path - Path to inspect
   * @returns File system info object
   */
  inspect(path: string): any;
}

import { filesystem } from "gluegun";

// Basic file operations
const config = filesystem.read("config.json", "json");
filesystem.write("output.txt", "Hello, world!");

// Path utilities
const homeDir = filesystem.homedir();
const configPath = filesystem.resolve(homeDir, ".myapp", "config.json");

// Directory operations
const subdirs = filesystem.subdirectories("./plugins", false, "*-plugin");
if (filesystem.isDirectory("./temp")) {
  filesystem.remove("./temp");
}

// File manipulation
if (filesystem.exists("package.json")) {
  const pkg = filesystem.read("package.json", "json");
  pkg.version = "1.1.0";
  filesystem.write("package.json", pkg);
}

/**
 * Get subdirectories with optional filtering
 * @param path - Directory to scan
 * @param isRelative - Return relative paths
 * @param matching - Glob pattern filter
 * @returns Array of subdirectory paths
 */
subdirectories(path: string, isRelative?: boolean, matching?: string): string[];

/**
 * Directory existence checking
 * @param path - Path to check
 * @returns True if directory exists
 */
isDirectory(path: string): boolean;

/**
 * Inverse directory check
 * @param path - Path to check
 * @returns True if not a directory
 */
isNotDirectory(path: string): boolean;

// Find all plugin directories
const pluginDirs = filesystem.subdirectories("./node_modules", false, "*-plugin");

// Check directory structure
if (filesystem.isDirectory("./src/commands")) {
  const commands = filesystem.list("./src/commands")
    .filter(file => file.endsWith(".js"));
}

// Safe directory operations
const tempDir = "./temp";
if (filesystem.isNotDirectory(tempDir)) {
  filesystem.dir(tempDir);
}

/**
 * Type-safe file reading
 * @param path - File path
 * @param returnAs - Return format
 * @returns Content in specified format
 */
read(path: string, returnAs?: 'utf8' | 'buffer' | 'json' | 'jsonWithDates'): string | Buffer | object | null;

/**
 * Flexible file writing
 * @param path - File path
 * @param data - Content to write
 * @param options - Write options
 * @returns Written file path
 */
write(path: string, data: string | Buffer | object, options?: any): string;

/**
 * File existence checking
 * @param path - Path to check
 * @returns True if file exists
 */
isFile(path: string): boolean;

// JSON file handling
const packageJson = filesystem.read("package.json", "json");
packageJson.scripts.build = "tsc";
filesystem.write("package.json", packageJson);

// Text file operations
const template = filesystem.read("template.txt");
const output = template.replace("{{name}}", "MyProject");
filesystem.write("output.txt", output);

// Binary file handling
const imageBuffer = filesystem.read("image.png", "buffer");
filesystem.write("copy.png", imageBuffer);

// Safe file operations
if (filesystem.isFile("config.json")) {
  const config = filesystem.read("config.json", "json");
  // Process config...
}

/** OS-specific path separator */
separator: string;

/** OS-specific end-of-line character */
eol: string;

/** Get user home directory */
homedir(): string;

/** Resolve path segments to absolute path */
resolve: typeof import('path').resolve;

/** Change file permissions */
chmodSync: typeof import('fs').chmodSync;

// Cross-platform path building
const configDir = filesystem.resolve(filesystem.homedir(), ".myapp");
const configFile = `${configDir}${filesystem.separator}config.json`;

// Text file with proper line endings
const content = `Line 1${filesystem.eol}Line 2${filesystem.eol}`;
filesystem.write("text.txt", content);

// File permissions (Unix-like systems)
filesystem.write("script.sh", "#!/bin/bash\necho 'Hello'");
filesystem.chmodSync("script.sh", "755");

/**
 * Find files matching criteria
 * @param path - Search root path
 * @param searchCriteria - Search options object
 * @returns Array of matching file paths
 */
find(path: string, searchCriteria?: {
  matching?: string | string[];
  files?: boolean;
  directories?: boolean;
  recursive?: boolean;
}): string[];

/**
 * List directory contents
 * @param path - Directory path
 * @returns Array of item names
 */
list(path: string): string[];

/**
 * Get directory tree structure
 * @param path - Directory path
 * @returns Nested tree object
 */
tree(path: string): {
  name: string;
  type: 'file' | 'dir';
  size?: number;
  children?: any[];
};

// Find all TypeScript files
const tsFiles = filesystem.find("./src", {
  matching: "*.ts",
  files: true,
  recursive: true
});

// Find command directories
const commandDirs = filesystem.find("./plugins", {
  matching: "commands",
  directories: true,
  recursive: true
});

// Directory listing
const srcContents = filesystem.list("./src");
const jsFiles = srcContents.filter(item => 
  filesystem.isFile(`./src/${item}`) && item.endsWith(".js")
);