@n0zer0d4y/vulcan-file-ops 1.0.1

package/dist/utils/path-utils.js

@@ -0,0 +1,92 @@
+import path from "path";
+import os from 'os';
+/**
+ * Converts WSL or Unix-style Windows paths to Windows format
+ * @param p The path to convert
+ * @returns Converted Windows path
+ */
+export function convertToWindowsPath(p) {
+    // Handle WSL paths (/mnt/c/...)
+    if (p.startsWith('/mnt/')) {
+        const driveLetter = p.charAt(5).toUpperCase();
+        const pathPart = p.slice(6).replace(/\//g, '\\');
+        return `${driveLetter}:${pathPart}`;
+    }
+    // Handle Unix-style Windows paths (/c/...)
+    if (p.match(/^\/[a-zA-Z]\//)) {
+        const driveLetter = p.charAt(1).toUpperCase();
+        const pathPart = p.slice(2).replace(/\//g, '\\');
+        return `${driveLetter}:${pathPart}`;
+    }
+    // Handle standard Windows paths, ensuring backslashes
+    if (p.match(/^[a-zA-Z]:/)) {
+        return p.replace(/\//g, '\\');
+    }
+    // Leave non-Windows paths unchanged
+    return p;
+}
+/**
+ * Normalizes path by standardizing format while preserving OS-specific behavior
+ * @param p The path to normalize
+ * @returns Normalized path
+ */
+export function normalizePath(p) {
+    // Remove any surrounding quotes and whitespace
+    p = p.trim().replace(/^["']|["']$/g, '');
+    // Check if this is a Unix path (starts with / but not a Windows or WSL path)
+    const isUnixPath = p.startsWith('/') &&
+        !p.match(/^\/mnt\/[a-z]\//i) &&
+        !p.match(/^\/[a-zA-Z]\//);
+    if (isUnixPath) {
+        // For Unix paths, just normalize without converting to Windows format
+        // Replace double slashes with single slashes and remove trailing slashes
+        return p.replace(/\/+/g, '/').replace(/\/+$/, '');
+    }
+    // Convert WSL or Unix-style Windows paths to Windows format
+    p = convertToWindowsPath(p);
+    // Handle double backslashes, preserving leading UNC \\
+    if (p.startsWith('\\\\')) {
+        // For UNC paths, first normalize any excessive leading backslashes to exactly \\
+        // Then normalize double backslashes in the rest of the path
+        let uncPath = p;
+        // Replace multiple leading backslashes with exactly two
+        uncPath = uncPath.replace(/^\\{2,}/, '\\\\');
+        // Now normalize any remaining double backslashes in the rest of the path
+        const restOfPath = uncPath.substring(2).replace(/\\\\/g, '\\');
+        p = '\\\\' + restOfPath;
+    }
+    else {
+        // For non-UNC paths, normalize all double backslashes
+        p = p.replace(/\\\\/g, '\\');
+    }
+    // Use Node's path normalization, which handles . and .. segments
+    let normalized = path.normalize(p);
+    // Fix UNC paths after normalization (path.normalize can remove a leading backslash)
+    if (p.startsWith('\\\\') && !normalized.startsWith('\\\\')) {
+        normalized = '\\' + normalized;
+    }
+    // Handle Windows paths: convert slashes and ensure drive letter is capitalized
+    if (normalized.match(/^[a-zA-Z]:/)) {
+        let result = normalized.replace(/\//g, '\\');
+        // Capitalize drive letter if present
+        if (/^[a-z]:/.test(result)) {
+            result = result.charAt(0).toUpperCase() + result.slice(1);
+        }
+        return result;
+    }
+    // For all other paths (including relative paths), convert forward slashes to backslashes
+    // This ensures relative paths like "some/relative/path" become "some\\relative\\path"
+    return normalized.replace(/\//g, '\\');
+}
+/**
+ * Expands home directory tildes in paths
+ * @param filepath The path to expand
+ * @returns Expanded path
+ */
+export function expandHome(filepath) {
+    if (filepath.startsWith('~/') || filepath === '~') {
+        return path.join(os.homedir(), filepath.slice(1));
+    }
+    return filepath;
+}
+//# sourceMappingURL=path-utils.js.map

package/dist/utils/path-validation.js

@@ -0,0 +1,76 @@
+import path from 'path';
+/**
+ * Checks if an absolute path is within any of the allowed directories.
+ *
+ * @param absolutePath - The absolute path to check (will be normalized)
+ * @param allowedDirectories - Array of absolute allowed directory paths (will be normalized)
+ * @returns true if the path is within an allowed directory, false otherwise
+ * @throws Error if given relative paths after normalization
+ */
+export function isPathWithinAllowedDirectories(absolutePath, allowedDirectories) {
+    // Type validation
+    if (typeof absolutePath !== 'string' || !Array.isArray(allowedDirectories)) {
+        return false;
+    }
+    // Reject empty inputs
+    if (!absolutePath || allowedDirectories.length === 0) {
+        return false;
+    }
+    // Reject null bytes (forbidden in paths)
+    if (absolutePath.includes('\x00')) {
+        return false;
+    }
+    // Normalize the input path
+    let normalizedPath;
+    try {
+        normalizedPath = path.resolve(path.normalize(absolutePath));
+    }
+    catch {
+        return false;
+    }
+    // Verify it's absolute after normalization
+    if (!path.isAbsolute(normalizedPath)) {
+        throw new Error('Path must be absolute after normalization');
+    }
+    // Check against each allowed directory
+    return allowedDirectories.some(dir => {
+        if (typeof dir !== 'string' || !dir) {
+            return false;
+        }
+        // Reject null bytes in allowed dirs
+        if (dir.includes('\x00')) {
+            return false;
+        }
+        // Normalize the allowed directory
+        let normalizedDir;
+        try {
+            normalizedDir = path.resolve(path.normalize(dir));
+        }
+        catch {
+            return false;
+        }
+        // Verify allowed directory is absolute after normalization
+        if (!path.isAbsolute(normalizedDir)) {
+            throw new Error('Allowed directories must be absolute paths after normalization');
+        }
+        // Check if normalizedPath is within normalizedDir
+        // Path is inside if it's the same or a subdirectory
+        if (normalizedPath === normalizedDir) {
+            return true;
+        }
+        // Special case for root directory to avoid double slash
+        // On Windows, we need to check if both paths are on the same drive
+        if (normalizedDir === path.sep) {
+            return normalizedPath.startsWith(path.sep);
+        }
+        // On Windows, also check for drive root (e.g., "C:\")
+        if (path.sep === '\\' && normalizedDir.match(/^[A-Za-z]:\\?$/)) {
+            // Ensure both paths are on the same drive
+            const dirDrive = normalizedDir.charAt(0).toLowerCase();
+            const pathDrive = normalizedPath.charAt(0).toLowerCase();
+            return pathDrive === dirDrive && normalizedPath.startsWith(normalizedDir.replace(/\\?$/, '\\'));
+        }
+        return normalizedPath.startsWith(normalizedDir + path.sep);
+    });
+}
+//# sourceMappingURL=path-validation.js.map

package/dist/utils/pdf-writer.js

@@ -0,0 +1,94 @@
+import { PDFDocument, rgb, StandardFonts } from "pdf-lib";
+/**
+ * Create a new PDF document
+ */
+export async function createPDF(options = {}) {
+    const pdfDoc = await PDFDocument.create();
+    if (options.title)
+        pdfDoc.setTitle(options.title);
+    if (options.author)
+        pdfDoc.setAuthor(options.author);
+    if (options.subject)
+        pdfDoc.setSubject(options.subject);
+    if (options.keywords)
+        pdfDoc.setKeywords(options.keywords);
+    return pdfDoc;
+}
+/**
+ * Save PDF to buffer
+ */
+export async function savePDFToBuffer(pdfDoc) {
+    const pdfBytes = await pdfDoc.save();
+    return Buffer.from(pdfBytes);
+}
+/**
+ * Create simple text-based PDF from string content
+ * This is the main function called by write_file tool
+ */
+export async function createSimpleTextPDF(content, options = {}) {
+    const pdfDoc = await createPDF(options);
+    const font = await pdfDoc.embedFont(StandardFonts.Helvetica);
+    // A4 size: 595 x 842 points
+    const pageWidth = 595;
+    const pageHeight = 842;
+    const margin = 50;
+    const fontSize = 12;
+    const lineHeight = 14;
+    const maxWidth = pageWidth - 2 * margin;
+    let page = pdfDoc.addPage([pageWidth, pageHeight]);
+    let y = pageHeight - margin;
+    // Split content into lines
+    const lines = content.split("\n");
+    for (const line of lines) {
+        // Check if we need a new page
+        if (y < margin) {
+            page = pdfDoc.addPage([pageWidth, pageHeight]);
+            y = pageHeight - margin;
+        }
+        // Handle empty lines
+        if (line.trim() === "") {
+            y -= lineHeight;
+            continue;
+        }
+        // Simple word wrapping
+        const words = line.split(" ");
+        let currentLine = "";
+        for (const word of words) {
+            const testLine = currentLine + (currentLine ? " " : "") + word;
+            const textWidth = font.widthOfTextAtSize(testLine, fontSize);
+            if (textWidth > maxWidth && currentLine) {
+                // Draw current line and start new one
+                page.drawText(currentLine, {
+                    x: margin,
+                    y,
+                    size: fontSize,
+                    font,
+                    color: rgb(0, 0, 0),
+                });
+                y -= lineHeight;
+                currentLine = word;
+                // Check if we need a new page
+                if (y < margin) {
+                    page = pdfDoc.addPage([pageWidth, pageHeight]);
+                    y = pageHeight - margin;
+                }
+            }
+            else {
+                currentLine = testLine;
+            }
+        }
+        // Draw remaining text
+        if (currentLine) {
+            page.drawText(currentLine, {
+                x: margin,
+                y,
+                size: fontSize,
+                font,
+                color: rgb(0, 0, 0),
+            });
+            y -= lineHeight;
+        }
+    }
+    return await savePDFToBuffer(pdfDoc);
+}
+//# sourceMappingURL=pdf-writer.js.map

package/dist/utils/roots-utils.js

@@ -0,0 +1,71 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import { normalizePath } from './path-utils.js';
+/**
+ * Converts a root URI to a normalized directory path with basic security validation.
+ * @param rootUri - File URI (file://...) or plain directory path
+ * @returns Promise resolving to validated path or null if invalid
+ */
+async function parseRootUri(rootUri) {
+    try {
+        const rawPath = rootUri.startsWith('file://') ? rootUri.slice(7) : rootUri;
+        const expandedPath = rawPath.startsWith('~/') || rawPath === '~'
+            ? path.join(os.homedir(), rawPath.slice(1))
+            : rawPath;
+        const absolutePath = path.resolve(expandedPath);
+        const resolvedPath = await fs.realpath(absolutePath);
+        return normalizePath(resolvedPath);
+    }
+    catch {
+        return null; // Path doesn't exist or other error
+    }
+}
+/**
+ * Formats error message for directory validation failures.
+ * @param dir - Directory path that failed validation
+ * @param error - Error that occurred during validation
+ * @param reason - Specific reason for failure
+ * @returns Formatted error message
+ */
+function formatDirectoryError(dir, error, reason) {
+    if (reason) {
+        return `Skipping ${reason}: ${dir}`;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return `Skipping invalid directory: ${dir} due to error: ${message}`;
+}
+/**
+ * Resolves requested root directories from MCP root specifications.
+ *
+ * Converts root URI specifications (file:// URIs or plain paths) into normalized
+ * directory paths, validating that each path exists and is a directory.
+ * Includes symlink resolution for security.
+ *
+ * @param requestedRoots - Array of root specifications with URI and optional name
+ * @returns Promise resolving to array of validated directory paths
+ */
+export async function getValidRootDirectories(requestedRoots) {
+    const validatedDirectories = [];
+    for (const requestedRoot of requestedRoots) {
+        const resolvedPath = await parseRootUri(requestedRoot.uri);
+        if (!resolvedPath) {
+            console.error(formatDirectoryError(requestedRoot.uri, undefined, 'invalid path or inaccessible'));
+            continue;
+        }
+        try {
+            const stats = await fs.stat(resolvedPath);
+            if (stats.isDirectory()) {
+                validatedDirectories.push(resolvedPath);
+            }
+            else {
+                console.error(formatDirectoryError(resolvedPath, undefined, 'non-directory root'));
+            }
+        }
+        catch (error) {
+            console.error(formatDirectoryError(resolvedPath, error));
+        }
+    }
+    return validatedDirectories;
+}
+//# sourceMappingURL=roots-utils.js.map

package/dist/utils/shell-execution.js

@@ -0,0 +1,77 @@
+import { spawn } from "child_process";
+import { getShellConfig } from "./command-validation.js";
+/**
+ * Execute a shell command with proper security and resource management
+ */
+export async function executeShellCommand(command, options = {}) {
+    const { workdir = process.cwd(), timeout = 30000, env } = options;
+    const shellConfig = getShellConfig();
+    return new Promise((resolve) => {
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let resolved = false;
+        // Spawn the shell process
+        const child = spawn(shellConfig.shell, [...shellConfig.args, command], {
+            cwd: workdir,
+            env: { ...process.env, ...env },
+            shell: false, // Already using explicit shell
+            windowsHide: true,
+        });
+        // Set up timeout
+        const timeoutHandle = setTimeout(() => {
+            if (!resolved) {
+                timedOut = true;
+                child.kill("SIGTERM");
+                // Force kill after 5 seconds if SIGTERM doesn't work
+                setTimeout(() => {
+                    if (!resolved) {
+                        child.kill("SIGKILL");
+                    }
+                }, 5000);
+            }
+        }, timeout);
+        // Capture stdout
+        if (child.stdout) {
+            child.stdout.on("data", (data) => {
+                stdout += data.toString();
+            });
+        }
+        // Capture stderr
+        if (child.stderr) {
+            child.stderr.on("data", (data) => {
+                stderr += data.toString();
+            });
+        }
+        // Handle process completion
+        child.on("close", (exitCode, signal) => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearTimeout(timeoutHandle);
+            resolve({
+                stdout: stdout.trim(),
+                stderr: stderr.trim(),
+                exitCode,
+                signal,
+                timedOut,
+            });
+        });
+        // Handle errors
+        child.on("error", (error) => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearTimeout(timeoutHandle);
+            resolve({
+                stdout: stdout.trim(),
+                stderr: stderr.trim(),
+                exitCode: null,
+                signal: null,
+                timedOut: false,
+                error,
+            });
+        });
+    });
+}
+//# sourceMappingURL=shell-execution.js.map

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@n0zer0d4y/vulcan-file-ops",
+  "version": "1.0.1",
+  "description": "MCP server that gives Claude Desktop and other AI assistants filesystem superpowers—read, write, edit, and manage files like AI coding assistants",
+  "license": "MIT",
+  "author": "Lloyd Barcatan",
+  "homepage": "https://github.com/n0zer0d4y/vulcan-file-ops",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/n0zer0d4y/vulcan-file-ops.git"
+  },
+  "bugs": {
+    "url": "https://github.com/n0zer0d4y/vulcan-file-ops/issues"
+  },
+  "type": "module",
+  "bin": {
+    "vulcan-file-ops": "dist/cli.js"
+  },
+  "files": [
+    "dist/cli.js",
+    "dist/index.js",
+    "dist/server/index.js",
+    "dist/tools/*.js",
+    "dist/utils/*.js",
+    "dist/types/index.js",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc && shx chmod +x dist/*.js",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm test",
+    "watch": "tsc --watch",
+    "test": "jest --config=jest.config.cjs",
+    "test:coverage": "jest --config=jest.config.cjs --coverage",
+    "start": "node dist/index.js",
+    "lint:json": "node -e \"JSON.parse(require('fs').readFileSync('package.json'))\" && echo \"package.json is valid JSON\"",
+    "lint": "npm run lint:json"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.20.0",
+    "@turbodocx/html-to-docx": "^1.16.0",
+    "diff": "^8.0.2",
+    "docx": "^9.5.1",
+    "dotenv": "^17.2.3",
+    "glob": "^11.0.3",
+    "html-to-pdfmake": "^2.5.31",
+    "jsdom": "^27.0.1",
+    "mammoth": "^1.11.0",
+    "minimatch": "^10.0.3",
+    "officeparser": "^5.2.1",
+    "pdf-lib": "^1.17.1",
+    "pdf-parse": "^2.3.0",
+    "pdfmake": "^0.2.20",
+    "zod-to-json-schema": "^3.24.6"
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.2.0",
+    "@types/html-to-docx": "^1.8.0",
+    "@types/jest": "^30.0.0",
+    "@types/jsdom": "^27.0.0",
+    "@types/minimatch": "^5.1.2",
+    "@types/node": "^22",
+    "@types/pdf-parse": "^1.1.5",
+    "@types/pdfmake": "^0.2.12",
+    "jest": "^30.2.0",
+    "shx": "^0.3.4",
+    "ts-jest": "^29.4.5",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  }
+}