@n0zer0d4y/vulcan-file-ops 1.1.7 → 1.2.1

package/CHANGELOG.md

@@ -2,9 +2,55 @@
 
 All notable changes to this project will be documented in this file.
 
+
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+
+
+## [1.2.1] - 2025-12-07
+
+### Changed
+
+- Strengthened TypeScript types in `filesystem-tools` to eliminate implicit any usage in internal callbacks
+  - Added explicit string typing for directory exclude pattern matching
+  - Explicitly typed file operation inputs and indices in `file_operations` handling
+  - Clarified intermediate result typing for file operation workflows without altering runtime behavior
+- Improved overall type clarity for directory listing and file operations, preparing the codebase for stricter TypeScript configurations
+
+## [1.2.0] - 2025-12-07
+
+
+### Added
+
+- Automatic parent directory creation for write tools:
+  - `write_file` now detects when the target file's parent directory does not exist and, if the path is within approved directories, creates the full directory chain before writing
+  - `write_multiple_files` now validates all requested paths and automatically creates any missing parent directories within approved directories before performing concurrent writes
+  - This removes the need for the model to call `make_directory` explicitly before writing into new subdirectories, reducing round trips and tool calls
+- New `ValidatePathOptions` support for `validatePath` with `createParentIfMissing` flag:
+  - Optional flag that instructs `validatePath` to create missing parent directories, subject to strict allowed-directory and symlink safety checks
+  - Designed specifically for write operations; read/search tools continue to validate paths without side effects
+- Comprehensive test coverage for the new behavior:
+  - Unit tests for `validatePath` covering:
+    - Single-level and multi-level directory creation within allowed roots
+    - Rejection of paths outside allowed directories even when `createParentIfMissing` is true
+    - Handling of race conditions where directories are created between checks
+    - Defensive behavior when an expected directory segment is actually a file
+    - Symlink interactions to ensure created directories do not escape approved roots
+  - Integration tests for:
+    - `write_file` writing into deep, initially non-existent directory trees
+    - `write_multiple_files` writing multiple files into separate, initially non-existent directory trees
+    - Ensuring multi-file writes still fail cleanly when any path is outside approved directories
+
+### Changed
+
+- `handleWriteTool` implementation for `write_file` and `write_multiple_files` now opts into `validatePath(path, { createParentIfMissing: true })` for write operations only, preserving existing behavior for all other tools
+- Internal path-validation logic refactored to centralize secure directory creation semantics in `validatePath`, ensuring:
+  - Normalization and allowed-directory checks are performed before any directory creation
+  - Each created directory is validated with `realpath` to stay inside allowed roots
+  - Non-directory collisions and unsafe symlink targets are rejected with clear error messages
+
 ## [1.1.7] - 2025-11-18
 
 ### Security

package/README.md

@@ -496,6 +496,11 @@ Create or replace file content
 
 **Note:** This tool is limited to single-file operations only. **RECOMMENDED:** Use `write_multiple_files` instead, which supports both single and batch file operations for greater flexibility.
 
+**Automatic directory creation:**
+
+- If the target file's parent directory does not exist but is inside your configured approved folders, the server will automatically create the required directory structure before writing the file
+- If the path is outside approved folders, the operation fails with a clear error and no directories are created
+
 **Input:**
 
 - `path` (string): File path
@@ -507,6 +512,11 @@ Create or replace file content
 
 Create or replace multiple files concurrently
 
+**Automatic directory creation:**
+
+- For each requested file, if the parent directory does not exist but is inside your configured approved folders, the server will automatically create the required directory structure before writing
+- Paths outside approved folders are rejected during validation and no directories are created; the operation fails with a detailed list of invalid paths
+
 **Input:**
 
 - `files` (array): List of file objects with path and content

package/dist/tools/filesystem-tools.js

@@ -158,9 +158,6 @@ async function collectFileEntry(entryPath, dirent) {
         };
     }
 }
-/**
- * Helper: Filter entries and collect metadata
- */
 async function filterAndCollectEntries(rawEntries, basePath, args) {
     let excludedByPatterns = 0;
     let excludedByIgnoreRules = 0;
@@ -171,7 +168,6 @@ async function filterAndCollectEntries(rawEntries, basePath, args) {
             excludedByIgnoreRules++;
             continue;
         }
-        // Check user exclude patterns
         if (args.excludePatterns && args.excludePatterns.length > 0) {
             const shouldExclude = args.excludePatterns.some((pattern) => {
                 return minimatch(dirent.name, pattern, { dot: true });

package/dist/tools/write-tools.js

@@ -77,8 +77,7 @@ async function processFileEditRequest(request, failOnAmbiguous = true) {
         const validPath = await validatePath(request.path);
         const result = await applyFileEdits(validPath, request.edits, request.dryRun || false, request.matchingStrategy || "auto", request.failOnAmbiguous !== undefined
             ? request.failOnAmbiguous
-            : failOnAmbiguous, true // Return metadata
-        );
+            : failOnAmbiguous, true);
         if (typeof result === "string") {
             throw new Error("Expected metadata but got string result");
         }
@@ -328,7 +327,9 @@ export async function handleWriteTool(name, args) {
             // 3. Symlink resolution and target validation (fs.realpath)
             // 4. Parent directory validation for new files
             // Prevents: CWE-23 (Path Traversal), CVE-2025-54794, CVE-2025-53109, CVE-2025-53110
-            const validPath = await validatePath(parsed.data.path);
+            const validPath = await validatePath(parsed.data.path, {
+                createParentIfMissing: true,
+            });
             await writeFileBasedOnExtension(validPath, parsed.data.content);
             return {
                 content: [
@@ -382,10 +383,12 @@ export async function handleWriteTool(name, args) {
             if (!parsed.success) {
                 throw new Error(`Invalid arguments for write_multiple_files: ${parsed.error}`);
             }
-            // Validate all paths before any writing
+            // Validate all paths before any writing, auto-creating parent directories
             const validationPromises = parsed.data.files.map(async (file) => {
                 try {
-                    const validPath = await validatePath(file.path);
+                    const validPath = await validatePath(file.path, {
+                        createParentIfMissing: true,
+                    });
                     return {
                         path: file.path,
                         validPath,

package/dist/utils/lib.js

@@ -194,8 +194,81 @@ export function createUnifiedDiff(originalContent, newContent, filepath = "file"
     const normalizedNew = normalizeLineEndings(newContent);
     return createTwoFilesPatch(filepath, filepath, normalizedOriginal, normalizedNew, "original", "modified");
 }
-// Security & Validation Functions
-export async function validatePath(requestedPath) {
+async function ensureParentDirectoryExists(absolutePath) {
+    const parentDir = path.dirname(absolutePath);
+    // Fast path: if parentDir already exists, let the existing logic handle it
+    try {
+        const realParentPath = await fs.realpath(parentDir);
+        const normalizedParent = normalizePath(realParentPath);
+        if (!isPathWithinAllowedDirectories(normalizedParent, allowedDirectories)) {
+            throw new Error(`Access denied - parent directory outside allowed directories: ${realParentPath} not in ${allowedDirectories.join(", ")}`);
+        }
+        return;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            // If it's not a "does not exist" error, rethrow and let validatePath handle it
+            throw error;
+        }
+    }
+    // Parent (or some ancestor) does not exist - we may need to create it.
+    // Security: We only create directories if the final requested path is
+    // within allowedDirectories (checked in validatePath before calling this),
+    // and we validate each created directory as we go.
+    const segments = [];
+    let current = parentDir;
+    // Walk up until we find an existing ancestor or hit filesystem root
+    // Note: We don't trust dirname("/") to progress forever; stop when stable.
+    while (true) {
+        segments.push(current);
+        const parent = path.dirname(current);
+        if (parent === current) {
+            break;
+        }
+        try {
+            await fs.lstat(current);
+            break; // Found an existing path
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                current = parent;
+                continue;
+            }
+            throw error;
+        }
+    }
+    // We collected segments from leaf up to the first existing ancestor/root.
+    // Create them from top-most missing down to the immediate parentDir.
+    for (let i = segments.length - 1; i >= 0; i--) {
+        const dir = segments[i];
+        // Normalize and check allowedDirectories before creating
+        const normalizedDir = normalizePath(dir);
+        if (!isPathWithinAllowedDirectories(normalizedDir, allowedDirectories)) {
+            throw new Error(`Access denied - cannot create directory outside allowed directories: ${dir} not in ${allowedDirectories.join(", ")}`);
+        }
+        try {
+            await fs.mkdir(dir);
+        }
+        catch (error) {
+            if (error.code === "EEXIST") {
+                // Something already exists at this path; verify it's a directory
+                const stats = await fs.lstat(dir);
+                if (!stats.isDirectory()) {
+                    throw new Error(`Cannot create directory; path exists and is not a directory: ${dir}`);
+                }
+                continue;
+            }
+            throw error;
+        }
+        // After creation, resolve real path and ensure it is still within allowed directories
+        const realCreatedPath = await fs.realpath(dir);
+        const normalizedCreated = normalizePath(realCreatedPath);
+        if (!isPathWithinAllowedDirectories(normalizedCreated, allowedDirectories)) {
+            throw new Error(`Access denied - created directory symlink target outside allowed directories: ${realCreatedPath} not in ${allowedDirectories.join(", ")}`);
+        }
+    }
+}
+export async function validatePath(requestedPath, options) {
     const expandedPath = expandHome(requestedPath);
     const absolute = path.isAbsolute(expandedPath)
         ? path.resolve(expandedPath)
@@ -206,6 +279,7 @@ export async function validatePath(requestedPath) {
     if (!isAllowed) {
         throw new Error(`Access denied - path outside allowed directories: ${absolute} not in ${allowedDirectories.join(", ")}`);
     }
+    const createParentIfMissing = options?.createParentIfMissing === true;
     // Security: Handle symlinks by checking their real path to prevent symlink attacks
     // This prevents attackers from creating symlinks that point outside allowed directories
     try {
@@ -229,8 +303,16 @@ export async function validatePath(requestedPath) {
                 }
                 return absolute;
             }
-            catch {
-                throw new Error(`Parent directory does not exist: ${parentDir}`);
+            catch (parentError) {
+                if (!createParentIfMissing) {
+                    throw new Error(`Parent directory does not exist: ${parentDir}`);
+                }
+                // Attempt to securely create the missing parent directory chain
+                await ensureParentDirectoryExists(absolute);
+                // After creation, return the absolute path for the new file. We intentionally
+                // do not call fs.realpath on the file itself here, because it still may not
+                // exist yet (for new files).
+                return absolute;
             }
         }
         throw error;
@@ -564,7 +646,7 @@ export async function applyFileEdits(filePath, edits, dryRun = false, matchingSt
     if (returnMetadata) {
         return {
             diff: formattedDiff,
-            metadata: editResults
+            metadata: editResults,
         };
     }
     return formattedDiff;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@n0zer0d4y/vulcan-file-ops",
-  "version": "1.1.7",
+  "version": "1.2.1",
   "mcpName": "io.github.n0zer0d4y/vulcan-file-ops",
   "description": "MCP server for AI assistants: read, write, edit, and manage files securely on local filesystem.",
   "license": "MIT",