@j0hanz/filesystem-mcp 1.19.0 → 2.0.0

package/dist/lib/errors.js

@@ -1,301 +0,0 @@
-import { constants as osConstants } from 'node:os';
-import { getSystemErrorMap, getSystemErrorName, inspect } from 'node:util';
-import { ErrorCode, joinLines } from '../config.js';
-import { getTraceContext } from './observability.js';
-export { ErrorCode };
-function isNativeError(error) {
-    const candidate = Error;
-    if (typeof candidate.isError === 'function') {
-        return candidate.isError(error);
-    }
-    return error instanceof Error;
-}
-export function isNodeError(error) {
-    if (!isNativeError(error))
-        return false;
-    if (!('code' in error))
-        return false;
-    const { code } = error;
-    return typeof code === 'string';
-}
-function getNodeErrno(error) {
-    if (!isNativeError(error))
-        return undefined;
-    if (!('errno' in error))
-        return undefined;
-    const { errno } = error;
-    if (typeof errno !== 'number' || !Number.isInteger(errno))
-        return undefined;
-    return errno;
-}
-function messageIncludesAny(message, patterns) {
-    return patterns.some((pattern) => message.includes(pattern));
-}
-const ERRNO_CODE_BY_VALUE = new Map();
-const SYSTEM_ERROR_MAP = getSystemErrorMap();
-for (const [name, value] of Object.entries(osConstants.errno)) {
-    if (typeof value !== 'number')
-        continue;
-    if (!ERRNO_CODE_BY_VALUE.has(value)) {
-        ERRNO_CODE_BY_VALUE.set(value, name);
-    }
-}
-const ERROR_CODE_RE = /^[A-Z][A-Z0-9_]+$/u;
-function getSystemErrorNameFromMap(errno) {
-    const direct = SYSTEM_ERROR_MAP.get(errno);
-    if (direct)
-        return direct[0];
-    const normalized = SYSTEM_ERROR_MAP.get(-Math.abs(errno));
-    if (normalized)
-        return normalized[0];
-    return undefined;
-}
-function getNodeErrorCodeFromErrno(errno) {
-    const direct = ERRNO_CODE_BY_VALUE.get(errno);
-    if (direct)
-        return direct;
-    const normalized = ERRNO_CODE_BY_VALUE.get(Math.abs(errno));
-    if (normalized)
-        return normalized;
-    const fromMap = getSystemErrorNameFromMap(errno);
-    if (fromMap && ERROR_CODE_RE.test(fromMap))
-        return fromMap;
-    try {
-        const fromSystem = getSystemErrorName(errno <= 0 ? errno : -errno);
-        return ERROR_CODE_RE.test(fromSystem) ? fromSystem : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-function getNodeErrorCodeLabel(error) {
-    if (isNodeError(error))
-        return error.code;
-    const errno = getNodeErrno(error);
-    if (errno === undefined)
-        return undefined;
-    return getNodeErrorCodeFromErrno(errno);
-}
-export function formatUnknownErrorMessage(error) {
-    if (typeof error === 'string')
-        return error;
-    if (isNativeError(error))
-        return error.message;
-    try {
-        return inspect(error, {
-            depth: 3,
-            colors: false,
-            compact: 3,
-            breakLength: 80,
-            maxArrayLength: 50,
-            maxStringLength: 2000,
-        });
-    }
-    catch {
-        return String(error);
-    }
-}
-export function normalizeUnknownError(error) {
-    return error instanceof Error
-        ? error
-        : new Error(formatUnknownErrorMessage(error));
-}
-const NODE_ERROR_CODE_MAP = {
-    ENOENT: ErrorCode.NOT_FOUND,
-    EACCES: ErrorCode.PERMISSION_DENIED,
-    EPERM: ErrorCode.PERMISSION_DENIED,
-    ENOTDIR: ErrorCode.NOT_DIRECTORY,
-    EISDIR: ErrorCode.NOT_FILE,
-    ELOOP: ErrorCode.SYMLINK_NOT_ALLOWED,
-    ENAMETOOLONG: ErrorCode.INVALID_INPUT,
-    ETIMEDOUT: ErrorCode.TIMEOUT,
-    EMFILE: ErrorCode.TIMEOUT,
-    ENFILE: ErrorCode.TIMEOUT,
-    EBUSY: ErrorCode.PERMISSION_DENIED,
-    ENOTEMPTY: ErrorCode.NOT_DIRECTORY,
-    EEXIST: ErrorCode.INVALID_INPUT,
-    EINVAL: ErrorCode.INVALID_INPUT,
-};
-function isKnownNodeErrorCode(code) {
-    return code in NODE_ERROR_CODE_MAP;
-}
-function getNodeErrorCode(code) {
-    return isKnownNodeErrorCode(code) ? NODE_ERROR_CODE_MAP[code] : undefined;
-}
-function walkErrorChain(error, visitor) {
-    let current = error;
-    const visited = new Set();
-    while (current !== undefined && current !== null && !visited.has(current)) {
-        const visitedResult = visitor(current);
-        if (visitedResult !== undefined)
-            return visitedResult;
-        if (!isNativeError(current))
-            break;
-        visited.add(current);
-        const next = current.cause;
-        current = next;
-    }
-    return undefined;
-}
-function isAbortErrorSingle(error) {
-    if (!isNativeError(error))
-        return false;
-    if (error.name === 'AbortError')
-        return true;
-    const code = getNodeErrorCodeLabel(error);
-    return code === 'ABORT_ERR';
-}
-export function isAbortError(error) {
-    return (walkErrorChain(error, (candidate) => isAbortErrorSingle(candidate) ? true : undefined) === true);
-}
-function isTimeoutErrorSingle(error) {
-    if (!isNativeError(error))
-        return false;
-    if (error.name === 'TimeoutError')
-        return true;
-    const code = getNodeErrorCodeLabel(error);
-    if (code === 'ETIMEDOUT')
-        return true;
-    const message = error.message.toLowerCase();
-    return message.includes('timed out') || message.includes('timeout');
-}
-export function isTimeoutLikeError(error) {
-    return (walkErrorChain(error, (candidate) => isTimeoutErrorSingle(candidate) ? true : undefined) === true);
-}
-export class McpError extends Error {
-    code;
-    path;
-    details;
-    constructor(code, message, path, details, cause) {
-        super(message, { cause });
-        this.code = code;
-        this.path = path;
-        this.name = 'McpError';
-        Object.setPrototypeOf(this, McpError.prototype);
-        const trace = getTraceContext();
-        if (trace?.traceparent || details) {
-            this.details = { ...trace, ...details };
-        }
-    }
-    static notFound(message, path, details, cause) {
-        return new McpError(ErrorCode.NOT_FOUND, message, path, details, cause);
-    }
-    static invalidInput(message, path, details, cause) {
-        return new McpError(ErrorCode.INVALID_INPUT, message, path, details, cause);
-    }
-    static accessDenied(message, path, details, cause) {
-        return new McpError(ErrorCode.ACCESS_DENIED, message, path, details, cause);
-    }
-    static timeout(message, path, details, cause) {
-        return new McpError(ErrorCode.TIMEOUT, message, path, details, cause);
-    }
-}
-const ERROR_SUGGESTIONS = {
-    [ErrorCode.ACCESS_DENIED]: 'Run roots to list allowed directories.',
-    [ErrorCode.NOT_FOUND]: 'Run ls or find to verify the path.',
-    [ErrorCode.NOT_FILE]: 'Target is a directory, not a file.',
-    [ErrorCode.NOT_DIRECTORY]: 'Target is a file, not a directory.',
-    [ErrorCode.TOO_LARGE]: 'Use head/tail or line ranges to read partially.',
-    [ErrorCode.TIMEOUT]: 'Reduce scope, depth, or maxResults.',
-    [ErrorCode.CANCELLED]: undefined,
-    [ErrorCode.INVALID_PATTERN]: 'Check syntax and escape special characters.',
-    [ErrorCode.INVALID_INPUT]: undefined,
-    [ErrorCode.PERMISSION_DENIED]: 'Check OS file permissions.',
-    [ErrorCode.SYMLINK_NOT_ALLOWED]: 'Symlink escapes allowed directories.',
-    [ErrorCode.UNKNOWN]: undefined,
-};
-const NOT_FOUND_PATTERNS = [
-    'no such file or directory',
-    'does not exist',
-];
-const PERMISSION_DENIED_PATTERNS = [
-    'permission denied',
-    'not permitted',
-];
-function getDirectErrorCode(error) {
-    if (error instanceof McpError) {
-        return error.code;
-    }
-    const code = getNodeErrorCodeLabel(error);
-    return code ? getNodeErrorCode(code) : undefined;
-}
-function classifyMessageError(error) {
-    const message = isNativeError(error) ? error.message : String(error);
-    const lower = message.toLowerCase();
-    if (messageIncludesAny(lower, NOT_FOUND_PATTERNS)) {
-        return ErrorCode.NOT_FOUND;
-    }
-    if (messageIncludesAny(lower, PERMISSION_DENIED_PATTERNS)) {
-        return ErrorCode.PERMISSION_DENIED;
-    }
-    if (lower.includes('not a directory')) {
-        return ErrorCode.NOT_DIRECTORY;
-    }
-    if (lower.includes('is a directory')) {
-        return ErrorCode.NOT_FILE;
-    }
-    return undefined;
-}
-export function classifyError(error) {
-    let timeoutCode;
-    let fallbackCode;
-    const terminalCode = walkErrorChain(error, (candidate) => {
-        if (isAbortErrorSingle(candidate)) {
-            return ErrorCode.CANCELLED;
-        }
-        if (timeoutCode === undefined && isTimeoutErrorSingle(candidate)) {
-            timeoutCode = ErrorCode.TIMEOUT;
-        }
-        fallbackCode ??=
-            getDirectErrorCode(candidate) ?? classifyMessageError(candidate);
-        return undefined;
-    });
-    return terminalCode ?? timeoutCode ?? fallbackCode ?? ErrorCode.UNKNOWN;
-}
-export function createDetailedError(error, path, additionalDetails) {
-    const message = formatUnknownErrorMessage(error);
-    const code = classifyError(error);
-    const suggestion = ERROR_SUGGESTIONS[code];
-    const resolvedPath = resolveErrorPath(error, path);
-    const details = mergeErrorDetails(error, additionalDetails);
-    const result = {
-        code,
-        message,
-        ...(suggestion ? { suggestion } : {}),
-    };
-    if (resolvedPath)
-        result.path = resolvedPath;
-    if (details)
-        result.details = details;
-    return result;
-}
-function resolveErrorPath(error, path) {
-    if (path)
-        return path;
-    if (error instanceof McpError)
-        return error.path;
-    return undefined;
-}
-function mergeErrorDetails(error, additionalDetails) {
-    const mcpDetails = error instanceof McpError ? error.details : undefined;
-    const mergedDetails = {
-        ...mcpDetails,
-        ...additionalDetails,
-    };
-    if (Object.keys(mergedDetails).length === 0)
-        return undefined;
-    return mergedDetails;
-}
-export function formatDetailedError(error) {
-    const lines = [`${error.code}: ${error.message}`];
-    if (error.path && !error.message.includes(error.path)) {
-        lines.push(error.path);
-    }
-    if (error.suggestion) {
-        lines.push(error.suggestion);
-    }
-    return joinLines(lines);
-}
-export function getSuggestion(code) {
-    return ERROR_SUGGESTIONS[code];
-}

package/dist/lib/file-operations/core.d.ts

@@ -1,53 +0,0 @@
-import { type Ignore } from 'ignore';
-export declare function needsStatsForSort(sortBy: string): boolean;
-export declare function withOptionalStoppedReason<T extends object, R extends string>(summary: T, stoppedReason: R | undefined): T & {
-    stoppedReason?: R;
-};
-export interface DirentLike {
-    isDirectory(): boolean;
-    isFile(): boolean;
-    isSymbolicLink(): boolean;
-}
-export type EntryType = 'file' | 'directory' | 'symlink' | 'other';
-interface IndexedValue<T> {
-    index: number;
-    value: T;
-}
-interface IndexedError {
-    index: number;
-    error: Error;
-}
-export declare function resolveEntryType(dirent: DirentLike): EntryType;
-export declare function resolveStopReason<R extends string>(options: {
-    signal: AbortSignal;
-    current: number;
-    max: number;
-    abortedReason: R;
-    maxReason: R;
-}): R | undefined;
-export declare function compareStringValues(left?: string, right?: string): number;
-export declare function compareOptionalNumberDesc(left: number | undefined, right: number | undefined, tieBreak: () => number): number;
-export declare function stableSortByDerivedString<T>(items: T[], derive: (item: T) => string, tieBreak: (left: T, right: T) => number): void;
-export declare function applyIndexedValues<T>(output: T[], results: readonly IndexedValue<T>[]): void;
-export declare function applyIndexedErrors<T>(options: {
-    output: T[];
-    errors: readonly IndexedError[];
-    resolveIndex: (failureIndex: number) => number | undefined;
-    buildValue: (resolvedIndex: number, error: Error) => T;
-}): void;
-export interface EntryAccessDependencies {
-    normalizePath: (inputPath: string) => string;
-    isPathWithinDirectories: (normalizedPath: string, rootDirectories: readonly string[]) => boolean;
-    isSensitivePath: (requestedPath: string, resolvedPath: string) => boolean;
-    validateSymlinkPath: (inputPath: string, signal: AbortSignal) => Promise<{
-        requestedPath: string;
-        resolvedPath: string;
-    }>;
-}
-export declare function isEntryAccessibleByType(entryPath: string, entryType: EntryType, rootDirectories: readonly string[], signal: AbortSignal, deps: EntryAccessDependencies): Promise<boolean>;
-export declare function loadRootGitignore(root: string, signal?: AbortSignal): Promise<Ignore | null>;
-export declare function isIgnoredByGitignore(matcher: Ignore, root: string, absolutePath: string, options?: {
-    isDirectory?: boolean;
-    relativePath?: string;
-}): boolean;
-export {};

package/dist/lib/file-operations/core.js

@@ -1,144 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { join, relative } from 'node:path';
-import ignore, {} from 'ignore';
-import { isNodeError } from '../errors.js';
-import { toPosixPath } from '../paths.js';
-export function needsStatsForSort(sortBy) {
-    return sortBy === 'size' || sortBy === 'modified';
-}
-const collator = new Intl.Collator(undefined, { numeric: true });
-export function withOptionalStoppedReason(summary, stoppedReason) {
-    if (stoppedReason === undefined) {
-        return summary;
-    }
-    return { ...summary, stoppedReason };
-}
-export function resolveEntryType(dirent) {
-    if (dirent.isSymbolicLink())
-        return 'symlink';
-    if (dirent.isDirectory())
-        return 'directory';
-    if (dirent.isFile())
-        return 'file';
-    return 'other';
-}
-export function resolveStopReason(options) {
-    if (options.signal.aborted)
-        return options.abortedReason;
-    if (options.current >= options.max)
-        return options.maxReason;
-    return undefined;
-}
-export function compareStringValues(left, right) {
-    return collator.compare(left ?? '', right ?? '');
-}
-export function compareOptionalNumberDesc(left, right, tieBreak) {
-    const diff = (right ?? 0) - (left ?? 0);
-    if (diff !== 0)
-        return diff;
-    return tieBreak();
-}
-export function stableSortByDerivedString(items, derive, tieBreak) {
-    const decorated = [];
-    const len = items.length;
-    for (let index = 0; index < len; index++) {
-        const item = items[index];
-        if (item === undefined)
-            continue;
-        decorated.push({
-            item,
-            derived: derive(item),
-            index,
-        });
-    }
-    decorated.sort((left, right) => {
-        const derivedCompare = compareStringValues(left.derived, right.derived);
-        if (derivedCompare !== 0)
-            return derivedCompare;
-        const tiedCompare = tieBreak(left.item, right.item);
-        if (tiedCompare !== 0)
-            return tiedCompare;
-        return left.index - right.index;
-    });
-    const decoratedLen = decorated.length;
-    for (let index = 0; index < decoratedLen; index++) {
-        const entry = decorated[index];
-        if (!entry)
-            continue;
-        items[index] = entry.item;
-    }
-}
-export function applyIndexedValues(output, results) {
-    for (const result of results) {
-        if (result.index < 0 || result.index >= output.length)
-            continue;
-        output[result.index] = result.value;
-    }
-}
-export function applyIndexedErrors(options) {
-    const { output, errors, resolveIndex, buildValue } = options;
-    for (const failure of errors) {
-        const resolvedIndex = resolveIndex(failure.index);
-        if (resolvedIndex === undefined)
-            continue;
-        if (resolvedIndex < 0 || resolvedIndex >= output.length)
-            continue;
-        output[resolvedIndex] = buildValue(resolvedIndex, failure.error);
-    }
-}
-export async function isEntryAccessibleByType(entryPath, entryType, rootDirectories, signal, deps) {
-    if (entryType !== 'symlink') {
-        const normalizedPath = deps.normalizePath(entryPath);
-        if (!deps.isPathWithinDirectories(normalizedPath, rootDirectories)) {
-            return false;
-        }
-        return !deps.isSensitivePath(entryPath, normalizedPath);
-    }
-    try {
-        const validated = await deps.validateSymlinkPath(entryPath, signal);
-        return !deps.isSensitivePath(validated.requestedPath, validated.resolvedPath);
-    }
-    catch {
-        return false;
-    }
-}
-function parseGitignoreLines(contents) {
-    const lines = [];
-    const parts = contents.split(/\r?\n/u);
-    for (const part of parts) {
-        const trimmed = part.trim();
-        if (trimmed.length > 0) {
-            lines.push(trimmed);
-        }
-    }
-    return lines;
-}
-export async function loadRootGitignore(root, signal) {
-    const gitignorePath = join(root, '.gitignore');
-    try {
-        const contents = await readFile(gitignorePath, {
-            encoding: 'utf-8',
-            signal,
-        });
-        const matcher = ignore();
-        matcher.add(parseGitignoreLines(contents));
-        return matcher;
-    }
-    catch (error) {
-        if (isNodeError(error) && error.code === 'ENOENT') {
-            return null;
-        }
-        throw error;
-    }
-}
-export function isIgnoredByGitignore(matcher, root, absolutePath, options = {}) {
-    let { relativePath } = options;
-    relativePath ??= relative(root, absolutePath);
-    if (relativePath.length === 0)
-        return false;
-    const normalized = toPosixPath(relativePath);
-    if (options.isDirectory) {
-        return matcher.ignores(normalized.endsWith('/') ? normalized : `${normalized}/`);
-    }
-    return matcher.ignores(normalized);
-}

package/dist/lib/file-operations/metadata.d.ts

@@ -1,77 +0,0 @@
-import type { FileInfo, GetMultipleFileInfoResult, ListDirectoryResult } from '../../config.js';
-import { type EntryType } from './core.js';
-interface FileInfoOptions {
-    includeMimeType?: boolean | undefined;
-    signal?: AbortSignal | undefined;
-    onProgress?: () => void;
-}
-export declare function getFileInfo(filePath: string, options?: FileInfoOptions): Promise<FileInfo>;
-type GetMultipleFileInfoOptions = FileInfoOptions;
-export declare function getMultipleFileInfo(paths: readonly string[], options?: GetMultipleFileInfoOptions): Promise<GetMultipleFileInfoResult>;
-interface ListDirectoryOptions {
-    includeHidden?: boolean;
-    excludePatterns?: readonly string[];
-    maxDepth?: number;
-    maxEntries?: number;
-    sortBy?: 'name' | 'size' | 'modified' | 'type';
-    includeSymlinkTargets?: boolean;
-    pattern?: string;
-    timeoutMs?: number;
-    signal?: AbortSignal;
-}
-export declare function listDirectory(dirPath: string, options?: ListDirectoryOptions): Promise<ListDirectoryResult>;
-interface TreeEntry {
-    name: string;
-    type: EntryType;
-    relativePath: string;
-    size?: number;
-    children?: TreeEntry[];
-}
-interface TreeOptions {
-    maxDepth?: number;
-    maxEntries?: number;
-    includeHidden?: boolean;
-    includeIgnored?: boolean;
-    includeSizes?: boolean;
-    timeoutMs?: number;
-    signal?: AbortSignal;
-    onProgress?: (progress: {
-        total?: number;
-        current: number;
-    }) => void;
-}
-interface TreeResult {
-    root: string;
-    tree: TreeEntry;
-    truncated: boolean;
-    totalEntries: number;
-}
-export declare function formatTreeAscii(tree: TreeEntry): string;
-export declare function treeDirectory(dirPath: string, options?: TreeOptions): Promise<TreeResult>;
-interface ReadMultipleResult {
-    path: string;
-    content?: string;
-    truncated?: boolean;
-    totalLines?: number;
-    readMode?: 'full' | 'head' | 'tail' | 'range';
-    head?: number;
-    tail?: number;
-    startLine?: number;
-    endLine?: number;
-    linesRead?: number;
-    hasMoreLines?: boolean;
-    error?: Error;
-}
-interface ReadMultipleOptions {
-    encoding?: BufferEncoding;
-    maxSize?: number;
-    maxTotalSize?: number;
-    head?: number;
-    tail?: number;
-    startLine?: number;
-    endLine?: number;
-    signal?: AbortSignal;
-    onReadComplete?: () => void;
-}
-export declare function readMultipleFiles(filePaths: readonly string[], options?: ReadMultipleOptions): Promise<ReadMultipleResult[]>;
-export {};