config-fs-utils 0.1.0

package/README.md

@@ -0,0 +1,348 @@
+# config-fs-utils
+
+File system utilities for configuration file management
+
+[![npm version](https://badge.fury.io/js/config-fs-utils.svg)](https://www.npmjs.com/package/config-fs-utils)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- ✅ **Zero dependencies** - Uses only Node.js built-in modules
+- ✅ **Simple & Flexible** - Two API styles for different use cases
+- ✅ **Safe file operations** - Automatic backups and permission management
+- ✅ **Tilde expansion** - Automatically expands `~` to home directory
+- ✅ **Recursive directory creation** - Creates nested directories automatically
+- ✅ **Perfect for config files** - Designed for configuration management
+
+## Installation
+
+```bash
+npm install config-fs-utils
+```
+
+## Quick Start
+
+### Simple API (Recommended for most users)
+
+```javascript
+const { setupStandardMuttDirs, writeConfigFiles } = require('config-fs-utils');
+
+// Create standard directory structure
+const dirs = await setupStandardMuttDirs();
+// Creates: ~/.config/mutt/, ~/.local/etc/oauth-tokens/, ~/.cache/mutt/, etc.
+
+// Write config files with automatic backups and secure permissions
+await writeConfigFiles({
+  '~/.config/myapp/config.ini': 'config content',
+  '~/.config/myapp/settings.json': JSON.stringify({ key: 'value' })
+});
+// Files are created with 0o600 permissions
+// Existing files are backed up automatically
+```
+
+### Flexible API (For advanced use cases)
+
+```javascript
+const { ensureDirectories, writeFile } = require('config-fs-utils');
+
+// Create custom directories
+await ensureDirectories([
+  '/custom/path/one',
+  '/custom/path/two',
+  '~/relative/path'
+]);
+
+// Write file with custom options
+await writeFile('/path/to/file', 'content', {
+  backup: false,
+  permissions: 0o644
+});
+```
+
+## API Reference
+
+### Simple API
+
+#### `setupStandardMuttDirs(options)`
+
+Creates standard Mutt/Neomutt directory structure.
+
+**Parameters:**
+- `options.baseDir` (string, optional): Base directory (defaults to `~`)
+
+**Returns:** Object with created directory paths
+
+```javascript
+const dirs = await setupStandardMuttDirs();
+// {
+//   config: '/Users/username/.config/mutt',
+//   accounts: '/Users/username/.config/mutt/accounts',
+//   tokens: '/Users/username/.local/etc/oauth-tokens',
+//   cacheHeaders: '/Users/username/.cache/mutt/headers',
+//   cacheBodies: '/Users/username/.cache/mutt/bodies'
+// }
+```
+
+#### `writeConfigFiles(files, options)`
+
+Writes multiple config files with secure defaults.
+
+**Parameters:**
+- `files` (Object): Map of filepath to content
+- `options.backup` (boolean, default: `true`): Create backups of existing files
+- `options.permissions` (number, default: `0o600`): File permissions
+
+**Returns:** Array of result objects
+
+```javascript
+const results = await writeConfigFiles({
+  '~/.config/app/config.yml': yamlContent,
+  '~/.config/app/secrets.json': secretsContent
+});
+// Each result: { path, backup, created }
+```
+
+### Flexible API
+
+#### `ensureDirectory(dir)`
+
+Creates a single directory (and parents if needed).
+
+```javascript
+await ensureDirectory('~/my/nested/directory');
+```
+
+#### `ensureDirectories(dirs)`
+
+Creates multiple directories.
+
+```javascript
+await ensureDirectories([
+  '~/dir1',
+  '~/dir2/nested',
+  '/absolute/path'
+]);
+```
+
+#### `writeFile(filepath, content, options)`
+
+Writes a single file with options.
+
+**Options:**
+- `backup` (boolean): Create backup if file exists
+- `permissions` (number): File permissions (e.g., `0o600`)
+
+```javascript
+const result = await writeFile('~/config.txt', 'content', {
+  backup: true,
+  permissions: 0o600
+});
+// { path: '/Users/username/config.txt', backup: '...backup-2026-01-26...', created: false }
+```
+
+#### `writeFiles(files, options)`
+
+Writes multiple files.
+
+```javascript
+await writeFiles({
+  '~/file1.txt': 'content1',
+  '~/file2.txt': 'content2'
+}, {
+  backup: true,
+  permissions: 0o644
+});
+```
+
+#### `backupFile(filepath)`
+
+Creates a backup of a file if it exists.
+
+```javascript
+const backupPath = await backupFile('~/important.txt');
+// Returns: '~/important.txt.backup-2026-01-26T12-34-56-789Z' or null
+```
+
+### Utility Functions
+
+#### `expandHome(filepath)`
+
+Expands `~` to home directory.
+
+```javascript
+expandHome('~/Documents');
+// Returns: '/Users/username/Documents'
+```
+
+#### `exists(filepath)`
+
+Checks if a file or directory exists.
+
+```javascript
+const fileExists = await exists('~/config.txt');
+// Returns: true or false
+```
+
+#### `getStats(filepath)`
+
+Gets file/directory stats.
+
+```javascript
+const stats = await getStats('~/file.txt');
+// Returns: fs.Stats object or null
+```
+
+#### `ensureDirectoriesFromPaths(paths)`
+
+Creates directories from a paths object (like from `mutt-config-core`).
+
+```javascript
+const { getConfigPaths } = require('mutt-config-core');
+const paths = getConfigPaths('user@gmail.com');
+
+await ensureDirectoriesFromPaths(paths);
+// Creates all necessary parent directories
+```
+
+### Constants
+
+#### `STANDARD_MUTT_DIRS`
+
+Array of standard Mutt directory paths:
+
+```javascript
+[
+  '.config/mutt',
+  '.config/mutt/accounts',
+  '.local/etc/oauth-tokens',
+  '.cache/mutt/headers',
+  '.cache/mutt/bodies'
+]
+```
+
+## Integration with mutt-config-core
+
+Perfect companion for [`mutt-config-core`](https://www.npmjs.com/package/mutt-config-core):
+
+```javascript
+const { generateMuttConfigs, getConfigPaths } = require('mutt-config-core');
+const { setupStandardMuttDirs, writeConfigFiles } = require('config-fs-utils');
+
+// 1. Generate configurations
+const configs = generateMuttConfigs({
+  email: 'user@gmail.com',
+  realName: 'John Doe',
+  editor: 'nvim',
+  locale: 'en'
+});
+
+// 2. Setup directories
+const dirs = await setupStandardMuttDirs();
+
+// 3. Write config files
+const paths = getConfigPaths('user@gmail.com');
+await writeConfigFiles({
+  [`~/${paths.accountMuttrc}`]: configs.accountMuttrc,
+  [`~/${paths.mainMuttrc}`]: configs.mainMuttrc
+});
+
+console.log('Setup complete!');
+```
+
+## Use Cases
+
+### Configuration Management
+
+```javascript
+// Safely update config files with automatic backups
+await writeConfigFiles({
+  '~/.bashrc': bashrcContent,
+  '~/.vimrc': vimrcContent,
+  '~/.gitconfig': gitconfigContent
+});
+```
+
+### Application Setup
+
+```javascript
+// Create app directory structure
+await ensureDirectories([
+  '~/.config/myapp',
+  '~/.config/myapp/plugins',
+  '~/.local/share/myapp',
+  '~/.cache/myapp'
+]);
+
+// Write initial config
+await writeFile('~/.config/myapp/config.json', JSON.stringify({
+  version: '1.0.0',
+  settings: {}
+}, null, 2));
+```
+
+### Secure File Operations
+
+```javascript
+// Write sensitive files with restricted permissions
+await writeFile('~/.ssh/id_rsa', privateKey, {
+  permissions: 0o600  // Owner read/write only
+});
+```
+
+## Error Handling
+
+All async functions can throw errors. Always use try-catch:
+
+```javascript
+try {
+  await writeConfigFiles({
+    '/protected/path': 'content'
+  });
+} catch (error) {
+  console.error('Failed to write config:', error.message);
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Watch mode
+npm run test:watch
+
+# Coverage
+npm run test:coverage
+```
+
+## Testing
+
+Fully tested with 29 test cases covering:
+- Directory creation (nested, recursive)
+- File operations (write, backup, permissions)
+- Tilde expansion
+- Path utilities
+- Integration scenarios
+
+## Related Projects
+
+- [mutt-config-core](https://github.com/a-lost-social-misfit/mutt-config-core) - Configuration generator
+- [create-neomutt-gmail](https://github.com/a-lost-social-misfit/create-neomutt-gmail) - CLI tool (coming soon)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT © a-lost-social-misfit
+
+## Author
+
+Created by [a-lost-social-misfit](https://github.com/a-lost-social-misfit)
+
+Part of a suite of tools for managing Neomutt + Gmail + OAuth2.0 setup.

package/index.js

@@ -0,0 +1,259 @@
+/**
+ * config-fs-utils
+ * File system utilities for configuration file management
+ *
+ * No external dependencies. Uses Node.js built-in modules only.
+ */
+
+const fs = require("fs").promises;
+const path = require("path");
+const os = require("os");
+
+/**
+ * Standard Mutt directory structure
+ */
+const STANDARD_MUTT_DIRS = [
+  ".config/mutt",
+  ".config/mutt/accounts",
+  ".local/etc/oauth-tokens",
+  ".cache/mutt/headers",
+  ".cache/mutt/bodies",
+];
+
+/**
+ * Expand tilde (~) to home directory
+ * @param {string} filepath - Path that may contain ~
+ * @returns {string} Expanded absolute path
+ */
+function expandHome(filepath) {
+  if (filepath.startsWith("~/") || filepath === "~") {
+    return path.join(os.homedir(), filepath.slice(2));
+  }
+  return filepath;
+}
+
+/**
+ * Ensure a single directory exists
+ * @param {string} dir - Directory path
+ * @returns {Promise<string>} Created directory path
+ */
+async function ensureDirectory(dir) {
+  const expandedDir = expandHome(dir);
+  await fs.mkdir(expandedDir, { recursive: true });
+  return expandedDir;
+}
+
+/**
+ * Ensure multiple directories exist
+ * @param {string[]} dirs - Array of directory paths
+ * @returns {Promise<string[]>} Array of created directory paths
+ */
+async function ensureDirectories(dirs) {
+  const results = [];
+  for (const dir of dirs) {
+    const created = await ensureDirectory(dir);
+    results.push(created);
+  }
+  return results;
+}
+
+/**
+ * Setup standard Mutt directory structure
+ * @param {Object} options - Options
+ * @param {string} [options.baseDir='~'] - Base directory (defaults to home)
+ * @returns {Promise<Object>} Created directory paths
+ */
+async function setupStandardMuttDirs(options = {}) {
+  const baseDir = options.baseDir || "~";
+  const dirs = STANDARD_MUTT_DIRS.map((dir) => path.join(baseDir, dir));
+
+  const created = await ensureDirectories(dirs);
+
+  return {
+    config: created[0],
+    accounts: created[1],
+    tokens: created[2],
+    cacheHeaders: created[3],
+    cacheBodies: created[4],
+  };
+}
+
+/**
+ * Create backup of a file if it exists
+ * @param {string} filepath - File to backup
+ * @returns {Promise<string|null>} Backup file path or null if file doesn't exist
+ */
+async function backupFile(filepath) {
+  const expandedPath = expandHome(filepath);
+
+  try {
+    await fs.access(expandedPath);
+    // File exists, create backup
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const backupPath = `${expandedPath}.backup-${timestamp}`;
+    await fs.copyFile(expandedPath, backupPath);
+    return backupPath;
+  } catch (error) {
+    // File doesn't exist, no backup needed
+    return null;
+  }
+}
+
+/**
+ * Write a single file with options
+ * @param {string} filepath - File path
+ * @param {string} content - File content
+ * @param {Object} options - Options
+ * @param {boolean} [options.backup=false] - Create backup if file exists
+ * @param {number} [options.permissions] - File permissions (e.g., 0o600)
+ * @returns {Promise<Object>} Result object
+ */
+async function writeFile(filepath, content, options = {}) {
+  const expandedPath = expandHome(filepath);
+  const dir = path.dirname(expandedPath);
+
+  // Ensure directory exists
+  await ensureDirectory(dir);
+
+  // Backup if requested
+  let backupPath = null;
+  if (options.backup) {
+    backupPath = await backupFile(expandedPath);
+  }
+
+  // Write file
+  await fs.writeFile(expandedPath, content, "utf8");
+
+  // Set permissions if specified
+  if (options.permissions !== undefined) {
+    await fs.chmod(expandedPath, options.permissions);
+  }
+
+  return {
+    path: expandedPath,
+    backup: backupPath,
+    created: backupPath === null,
+  };
+}
+
+/**
+ * Write multiple files at once
+ * @param {Object} files - Map of filepath to content
+ * @param {Object} options - Options
+ * @param {boolean} [options.backup=false] - Create backups
+ * @param {number} [options.permissions] - File permissions
+ * @returns {Promise<Object[]>} Array of result objects
+ */
+async function writeFiles(files, options = {}) {
+  const results = [];
+
+  for (const [filepath, content] of Object.entries(files)) {
+    const result = await writeFile(filepath, content, options);
+    results.push(result);
+  }
+
+  return results;
+}
+
+/**
+ * Write config files with standard permissions (0o600)
+ * @param {Object} files - Map of filepath to content
+ * @param {Object} options - Options
+ * @param {boolean} [options.backup=true] - Create backups (default: true)
+ * @returns {Promise<Object[]>} Array of result objects
+ */
+async function writeConfigFiles(files, options = {}) {
+  const defaultOptions = {
+    backup: true,
+    permissions: 0o600,
+    ...options,
+  };
+
+  return writeFiles(files, defaultOptions);
+}
+
+/**
+ * Check if a file or directory exists
+ * @param {string} filepath - Path to check
+ * @returns {Promise<boolean>} True if exists
+ */
+async function exists(filepath) {
+  const expandedPath = expandHome(filepath);
+  try {
+    await fs.access(expandedPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get file stats
+ * @param {string} filepath - File path
+ * @returns {Promise<Object|null>} Stats object or null if doesn't exist
+ */
+async function getStats(filepath) {
+  const expandedPath = expandHome(filepath);
+  try {
+    return await fs.stat(expandedPath);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Create directories from mutt-config-core paths object
+ * @param {Object} paths - Paths object from mutt-config-core
+ * @returns {Promise<string[]>} Created directories
+ */
+async function ensureDirectoriesFromPaths(paths) {
+  const dirs = new Set();
+
+  // Keys that represent files (not directories)
+  const fileKeys = ["accountmuttrc", "mainmuttrc"];
+
+  for (const [key, filepath] of Object.entries(paths)) {
+    const expandedPath = expandHome(filepath);
+    const normalizedKey = key.toLowerCase();
+
+    // Check if this is a file path or directory path
+    if (fileKeys.includes(normalizedKey)) {
+      // It's a file, create its parent directory
+      const dir = path.dirname(expandedPath);
+      dirs.add(dir);
+    } else {
+      // It's a directory path, create it directly
+      dirs.add(expandedPath);
+    }
+  }
+
+  return ensureDirectories(Array.from(dirs));
+}
+
+// Export API
+module.exports = {
+  // Simple API (most users)
+  setupStandardMuttDirs,
+  writeConfigFiles,
+
+  // Flexible API (advanced users)
+  ensureDirectory,
+  ensureDirectories,
+  writeFile,
+  writeFiles,
+  backupFile,
+
+  // Utility functions
+  expandHome,
+  exists,
+  getStats,
+  ensureDirectoriesFromPaths,
+
+  // Constants
+  STANDARD_MUTT_DIRS,
+};
+
+// For testing
+module.exports._internal = {
+  expandHome,
+};

package/index.test.js

@@ -0,0 +1,376 @@
+/**
+ * Tests for config-fs-utils
+ *
+ * Run with: npm test
+ */
+
+const fs = require("fs").promises;
+const path = require("path");
+const os = require("os");
+const {
+  setupStandardMuttDirs,
+  writeConfigFiles,
+  ensureDirectory,
+  ensureDirectories,
+  writeFile,
+  writeFiles,
+  backupFile,
+  expandHome,
+  exists,
+  getStats,
+  ensureDirectoriesFromPaths,
+  STANDARD_MUTT_DIRS,
+  _internal,
+} = require("./index");
+
+// Test utilities
+const TEST_DIR = path.join(os.tmpdir(), "config-fs-utils-test");
+
+beforeEach(async () => {
+  // Clean up test directory before each test
+  try {
+    await fs.rm(TEST_DIR, { recursive: true, force: true });
+  } catch (error) {
+    // Directory might not exist, ignore
+  }
+  await fs.mkdir(TEST_DIR, { recursive: true });
+});
+
+afterAll(async () => {
+  // Clean up after all tests
+  try {
+    await fs.rm(TEST_DIR, { recursive: true, force: true });
+  } catch (error) {
+    // Ignore cleanup errors
+  }
+});
+
+describe("config-fs-utils", () => {
+  describe("expandHome", () => {
+    test("expands ~ to home directory", () => {
+      const result = expandHome("~/test/path");
+      expect(result).toBe(path.join(os.homedir(), "test/path"));
+    });
+
+    test("expands ~ alone", () => {
+      const result = expandHome("~");
+      expect(result).toBe(os.homedir());
+    });
+
+    test("does not modify absolute paths", () => {
+      const result = expandHome("/absolute/path");
+      expect(result).toBe("/absolute/path");
+    });
+
+    test("does not modify relative paths", () => {
+      const result = expandHome("relative/path");
+      expect(result).toBe("relative/path");
+    });
+  });
+
+  describe("ensureDirectory", () => {
+    test("creates a single directory", async () => {
+      const testPath = path.join(TEST_DIR, "test-dir");
+      await ensureDirectory(testPath);
+
+      const stat = await fs.stat(testPath);
+      expect(stat.isDirectory()).toBe(true);
+    });
+
+    test("creates nested directories", async () => {
+      const testPath = path.join(TEST_DIR, "nested/deep/directory");
+      await ensureDirectory(testPath);
+
+      const stat = await fs.stat(testPath);
+      expect(stat.isDirectory()).toBe(true);
+    });
+
+    test("does not error if directory already exists", async () => {
+      const testPath = path.join(TEST_DIR, "existing-dir");
+      await fs.mkdir(testPath);
+
+      await expect(ensureDirectory(testPath)).resolves.not.toThrow();
+    });
+  });
+
+  describe("ensureDirectories", () => {
+    test("creates multiple directories", async () => {
+      const dirs = [
+        path.join(TEST_DIR, "dir1"),
+        path.join(TEST_DIR, "dir2"),
+        path.join(TEST_DIR, "dir3"),
+      ];
+
+      const created = await ensureDirectories(dirs);
+      expect(created).toHaveLength(3);
+
+      for (const dir of dirs) {
+        const stat = await fs.stat(dir);
+        expect(stat.isDirectory()).toBe(true);
+      }
+    });
+
+    test("returns created directory paths", async () => {
+      const dirs = [path.join(TEST_DIR, "test1"), path.join(TEST_DIR, "test2")];
+
+      const created = await ensureDirectories(dirs);
+      expect(created).toEqual(dirs);
+    });
+  });
+
+  describe("setupStandardMuttDirs", () => {
+    test("creates standard Mutt directory structure", async () => {
+      const result = await setupStandardMuttDirs({ baseDir: TEST_DIR });
+
+      expect(result).toHaveProperty("config");
+      expect(result).toHaveProperty("accounts");
+      expect(result).toHaveProperty("tokens");
+      expect(result).toHaveProperty("cacheHeaders");
+      expect(result).toHaveProperty("cacheBodies");
+
+      // Verify directories exist
+      for (const dir of Object.values(result)) {
+        const stat = await fs.stat(dir);
+        expect(stat.isDirectory()).toBe(true);
+      }
+    });
+
+    test("creates directories in home by default", async () => {
+      // We can't test actual home directory creation, but we can test the structure
+      const result = await setupStandardMuttDirs({ baseDir: TEST_DIR });
+
+      expect(result.config).toContain(".config/mutt");
+      expect(result.accounts).toContain(".config/mutt/accounts");
+      expect(result.tokens).toContain(".local/etc/oauth-tokens");
+    });
+  });
+
+  describe("backupFile", () => {
+    test("creates backup if file exists", async () => {
+      const testFile = path.join(TEST_DIR, "test.txt");
+      await fs.writeFile(testFile, "original content");
+
+      const backupPath = await backupFile(testFile);
+
+      expect(backupPath).not.toBeNull();
+      expect(backupPath).toContain(".backup-");
+
+      const backupContent = await fs.readFile(backupPath, "utf8");
+      expect(backupContent).toBe("original content");
+    });
+
+    test("returns null if file does not exist", async () => {
+      const testFile = path.join(TEST_DIR, "nonexistent.txt");
+      const backupPath = await backupFile(testFile);
+
+      expect(backupPath).toBeNull();
+    });
+  });
+
+  describe("writeFile", () => {
+    test("writes file with content", async () => {
+      const testFile = path.join(TEST_DIR, "test.txt");
+      await writeFile(testFile, "test content");
+
+      const content = await fs.readFile(testFile, "utf8");
+      expect(content).toBe("test content");
+    });
+
+    test("creates parent directories", async () => {
+      const testFile = path.join(TEST_DIR, "nested/deep/test.txt");
+      await writeFile(testFile, "test content");
+
+      const content = await fs.readFile(testFile, "utf8");
+      expect(content).toBe("test content");
+    });
+
+    test("creates backup when option is true", async () => {
+      const testFile = path.join(TEST_DIR, "test.txt");
+      await fs.writeFile(testFile, "original");
+
+      const result = await writeFile(testFile, "new content", { backup: true });
+
+      expect(result.backup).not.toBeNull();
+      expect(result.created).toBe(false);
+
+      const backupContent = await fs.readFile(result.backup, "utf8");
+      expect(backupContent).toBe("original");
+    });
+
+    test("sets file permissions", async () => {
+      const testFile = path.join(TEST_DIR, "test.txt");
+      await writeFile(testFile, "content", { permissions: 0o600 });
+
+      const stat = await fs.stat(testFile);
+      expect(stat.mode & 0o777).toBe(0o600);
+    });
+
+    test("returns result object", async () => {
+      const testFile = path.join(TEST_DIR, "test.txt");
+      const result = await writeFile(testFile, "content");
+
+      expect(result).toHaveProperty("path");
+      expect(result).toHaveProperty("backup");
+      expect(result).toHaveProperty("created");
+      expect(result.created).toBe(true);
+    });
+  });
+
+  describe("writeFiles", () => {
+    test("writes multiple files", async () => {
+      const files = {
+        [path.join(TEST_DIR, "file1.txt")]: "content1",
+        [path.join(TEST_DIR, "file2.txt")]: "content2",
+        [path.join(TEST_DIR, "file3.txt")]: "content3",
+      };
+
+      await writeFiles(files);
+
+      for (const [filepath, expectedContent] of Object.entries(files)) {
+        const content = await fs.readFile(filepath, "utf8");
+        expect(content).toBe(expectedContent);
+      }
+    });
+
+    test("returns array of results", async () => {
+      const files = {
+        [path.join(TEST_DIR, "file1.txt")]: "content1",
+        [path.join(TEST_DIR, "file2.txt")]: "content2",
+      };
+
+      const results = await writeFiles(files);
+
+      expect(results).toHaveLength(2);
+      expect(results[0]).toHaveProperty("path");
+      expect(results[1]).toHaveProperty("path");
+    });
+  });
+
+  describe("writeConfigFiles", () => {
+    test("writes files with 0o600 permissions by default", async () => {
+      const files = {
+        [path.join(TEST_DIR, "config.txt")]: "config content",
+      };
+
+      await writeConfigFiles(files);
+
+      const stat = await fs.stat(path.join(TEST_DIR, "config.txt"));
+      expect(stat.mode & 0o777).toBe(0o600);
+    });
+
+    test("creates backups by default", async () => {
+      const testFile = path.join(TEST_DIR, "config.txt");
+      await fs.writeFile(testFile, "original");
+
+      const results = await writeConfigFiles({
+        [testFile]: "new content",
+      });
+
+      expect(results[0].backup).not.toBeNull();
+    });
+  });
+
+  describe("exists", () => {
+    test("returns true for existing file", async () => {
+      const testFile = path.join(TEST_DIR, "exists.txt");
+      await fs.writeFile(testFile, "content");
+
+      const result = await exists(testFile);
+      expect(result).toBe(true);
+    });
+
+    test("returns false for non-existing file", async () => {
+      const testFile = path.join(TEST_DIR, "nonexistent.txt");
+      const result = await exists(testFile);
+      expect(result).toBe(false);
+    });
+
+    test("returns true for existing directory", async () => {
+      const result = await exists(TEST_DIR);
+      expect(result).toBe(true);
+    });
+  });
+
+  describe("getStats", () => {
+    test("returns stats for existing file", async () => {
+      const testFile = path.join(TEST_DIR, "test.txt");
+      await fs.writeFile(testFile, "content");
+
+      const stats = await getStats(testFile);
+      expect(stats).not.toBeNull();
+      expect(stats.isFile()).toBe(true);
+    });
+
+    test("returns null for non-existing file", async () => {
+      const testFile = path.join(TEST_DIR, "nonexistent.txt");
+      const stats = await getStats(testFile);
+      expect(stats).toBeNull();
+    });
+  });
+
+  describe("ensureDirectoriesFromPaths", () => {
+    test("creates directories from paths object", async () => {
+      const paths = {
+        accountMuttrc: path.join(
+          TEST_DIR,
+          ".config/mutt/accounts/test@gmail.com.muttrc"
+        ),
+        mainMuttrc: path.join(TEST_DIR, ".config/mutt/muttrc"),
+        oauthTokens: path.join(TEST_DIR, ".local/etc/oauth-tokens"),
+        cacheHeaders: path.join(TEST_DIR, ".cache/mutt/headers"),
+        cacheBodies: path.join(TEST_DIR, ".cache/mutt/bodies"),
+      };
+
+      await ensureDirectoriesFromPaths(paths);
+
+      // Check that parent directories were created for files
+      const accountsDir = await fs.stat(
+        path.join(TEST_DIR, ".config/mutt/accounts")
+      );
+      expect(accountsDir.isDirectory()).toBe(true);
+
+      const configDir = await fs.stat(path.join(TEST_DIR, ".config/mutt"));
+      expect(configDir.isDirectory()).toBe(true);
+
+      // Check that directory paths were created directly
+      const tokensDir = await fs.stat(
+        path.join(TEST_DIR, ".local/etc/oauth-tokens")
+      );
+      expect(tokensDir.isDirectory()).toBe(true);
+
+      const headersDir = await fs.stat(
+        path.join(TEST_DIR, ".cache/mutt/headers")
+      );
+      expect(headersDir.isDirectory()).toBe(true);
+    });
+  });
+
+  describe("Integration tests", () => {
+    test("complete workflow: setup dirs and write configs", async () => {
+      // Setup standard directories
+      const dirs = await setupStandardMuttDirs({ baseDir: TEST_DIR });
+
+      // Write config files
+      const files = {
+        [path.join(dirs.config, "muttrc")]: "main config",
+        [path.join(dirs.accounts, "test@gmail.com.muttrc")]: "account config",
+      };
+
+      const results = await writeConfigFiles(files);
+
+      // Verify files exist with correct content
+      const mainContent = await fs.readFile(
+        path.join(dirs.config, "muttrc"),
+        "utf8"
+      );
+      const accountContent = await fs.readFile(
+        path.join(dirs.accounts, "test@gmail.com.muttrc"),
+        "utf8"
+      );
+
+      expect(mainContent).toBe("main config");
+      expect(accountContent).toBe("account config");
+      expect(results).toHaveLength(2);
+    });
+  });
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "config-fs-utils",
+  "version": "0.1.0",
+  "description": "File system utilities for configuration file management",
+  "main": "index.js",
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
+  },
+  "keywords": [
+    "config",
+    "filesystem",
+    "utilities",
+    "backup",
+    "permissions",
+    "mutt",
+    "neomutt"
+  ],
+  "author": "a-lost-social-misfit",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/a-lost-social-misfit/config-fs-utils.git"
+  },
+  "devDependencies": {
+    "jest": "^30.2.0",
+    "mutt-config-core": "^0.1.0"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}