@j0hanz/filesystem-mcp 1.7.3 → 1.8.0

package/dist/lib/file-operations/glob-helpers.d.ts

@@ -0,0 +1,18 @@
+import type { globEntries } from './glob-engine.js';
+export interface GlobConfig {
+    cwd: string;
+    pattern: string;
+    excludePatterns?: readonly string[];
+    includeHidden?: boolean;
+    baseNameMatch?: boolean;
+    caseSensitiveMatch?: boolean;
+    followSymbolicLinks?: boolean;
+    onlyFiles?: boolean;
+    stats?: boolean;
+    maxDepth?: number;
+    suppressErrors?: boolean;
+}
+/**
+ * Builds standard options for globEntries to ensure consistency across search tools.
+ */
+export declare function buildGlobOptions(config: GlobConfig): Parameters<typeof globEntries>[0];

package/dist/lib/file-operations/glob-helpers.js

@@ -0,0 +1,23 @@
+/**
+ * Builds standard options for globEntries to ensure consistency across search tools.
+ */
+export function buildGlobOptions(config) {
+    const options = {
+        cwd: config.cwd,
+        pattern: config.pattern,
+        excludePatterns: config.excludePatterns ?? [],
+        includeHidden: config.includeHidden ?? false,
+        baseNameMatch: config.baseNameMatch ?? false,
+        caseSensitiveMatch: config.caseSensitiveMatch ?? true,
+        followSymbolicLinks: config.followSymbolicLinks ?? false,
+        onlyFiles: config.onlyFiles ?? true,
+        stats: config.stats ?? false,
+    };
+    if (config.suppressErrors) {
+        options.suppressErrors = config.suppressErrors;
+    }
+    if (config.maxDepth !== undefined) {
+        options.maxDepth = config.maxDepth;
+    }
+    return options;
+}

package/dist/lib/file-operations/list-directory.js

@@ -1,7 +1,7 @@
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
 import { DEFAULT_LIST_MAX_ENTRIES, DEFAULT_MAX_DEPTH, DEFAULT_SEARCH_TIMEOUT_MS, PARALLEL_CONCURRENCY, } from '../constants.js';
-import { createTimedAbortSignal, isHidden, processInParallel, withAbort, } from '../fs-helpers.js';
+import { isHidden, processInParallel, withAbort, withTimedAbortSignal, } from '../fs-helpers.js';
 import { isSensitivePath } from '../path-policy.js';
 import { isPathWithinDirectories, normalizePath, validateExistingDirectory, validateExistingPathDetailed, } from '../path-validation.js';
 import { isEntryAccessibleByType, needsStatsForSort, resolveEntryType, resolveStopReason, withOptionalStoppedReason, } from './common.js';
@@ -244,13 +244,9 @@ async function executeListDirectory(basePath, normalized, signal) {
 }
 export async function listDirectory(dirPath, options = {}) {
     const normalized = normalizeOptions(options);
-    const { signal, cleanup } = createTimedAbortSignal(options.signal, normalized.timeoutMs);
-    const basePath = await validateExistingDirectory(dirPath, signal);
-    try {
+    return withTimedAbortSignal(options.signal, normalized.timeoutMs, async (signal) => {
+        const basePath = await validateExistingDirectory(dirPath, signal);
         const { entries, summary } = await executeListDirectory(basePath, normalized, signal);
         return { path: basePath, entries, summary };
-    }
-    finally {
-        cleanup();
-    }
+    });
 }

package/dist/lib/file-operations/search-content.d.ts

@@ -1,12 +1,7 @@
 import * as fsp from 'node:fs/promises';
 import { z } from 'zod';
 import type { ContentMatch, SearchContentResult } from '../../config.js';
-export declare const MatcherOptionsSchema: z.ZodObject<{
-    caseSensitive: z.ZodBoolean;
-    wholeWord: z.ZodBoolean;
-    isLiteral: z.ZodBoolean;
-}, z.core.$strict>;
-export type MatcherOptions = z.infer<typeof MatcherOptionsSchema>;
+import type { Matcher, MatcherOptions } from './search-matcher.js';
 export interface ScanFileOptions {
     maxFileSize: number;
     skipBinary: boolean;
@@ -36,8 +31,6 @@ export interface SearchContentOptions extends Partial<ResolvedOptions> {
         current: number;
     }) => void;
 }
-export type Matcher = (line: string) => number;
-export declare function buildMatcher(pattern: string, options: MatcherOptions): Matcher;
 type BinaryDetector = (resolvedPath: string, handle: fsp.FileHandle, signal?: AbortSignal) => Promise<boolean>;
 export interface ScanRequest {
     type: 'scan';

package/dist/lib/file-operations/search-content.js

@@ -3,22 +3,19 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { Worker } from 'node:worker_threads';
 import { z } from 'zod';
-import RE2 from 're2';
-import safeRegex from 'safe-regex2';
 import { DEFAULT_EXCLUDE_PATTERNS, DEFAULT_SEARCH_MAX_FILES, DEFAULT_SEARCH_TIMEOUT_MS, MAX_LINE_CONTENT_LENGTH, MAX_SEARCHABLE_FILE_SIZE, SEARCH_WORKERS, } from '../constants.js';
 import { ErrorCode, formatUnknownErrorMessage, isTimeoutLikeError, McpError, } from '../errors.js';
-import { assertNotAborted, createTimedAbortSignal, isProbablyBinary, withAbort, } from '../fs-helpers.js';
+import { assertNotAborted, isProbablyBinary, withAbort, withTimedAbortSignal, } from '../fs-helpers.js';
+import { mergeOptions, omitOptionKeys } from '../option-utils.js';
 import { assertAllowedFileAccess, isSensitivePath } from '../path-policy.js';
 import { isPathWithinDirectories, normalizePath, validateExistingDirectory, validateExistingPathDetailed, } from '../path-validation.js';
+import { reportPeriodicProgress } from '../progress-reporting.js';
 import { withOptionalStoppedReason } from './common.js';
 import { globEntries } from './glob-engine.js';
+import { buildGlobOptions } from './glob-helpers.js';
+import { buildMatcher, validatePattern } from './search-matcher.js';
 // --- Configuration & Schemas ---
 const INTERNAL_MAX_RESULTS = 500;
-export const MatcherOptionsSchema = z.strictObject({
-    caseSensitive: z.boolean(),
-    wholeWord: z.boolean(),
-    isLiteral: z.boolean(),
-});
 const SearchOptionsSchema = z.strictObject({
     filePattern: z.string().min(1),
     excludePatterns: z.array(z.string()),
@@ -55,80 +52,14 @@ const ERROR_SCAN_CANCELLED = 'Scan cancelled';
 const ERROR_WORKER_POOL_CLOSED = 'Worker pool closed';
 // --- Helpers ---
 function resolveOptions(options) {
-    const rest = { ...options };
-    delete rest.signal;
-    delete rest.onProgress;
-    const merged = { ...DEFAULTS, ...rest };
+    const normalizedOptions = omitOptionKeys(options, ['signal', 'onProgress']);
+    const merged = mergeOptions(DEFAULTS, normalizedOptions);
     const result = SearchOptionsSchema.safeParse(merged);
     if (!result.success) {
         throw new McpError(ErrorCode.E_INVALID_INPUT, `Invalid search options: ${result.error.message}`, undefined, { errors: z.treeifyError(result.error) });
     }
     return result.data;
 }
-function countRegexLineMatches(regex, line) {
-    regex.lastIndex = 0;
-    let count = 0;
-    while (regex.exec(line) !== null) {
-        count++;
-        if (regex.lastIndex === 0)
-            regex.lastIndex++;
-    }
-    return count;
-}
-function escapeLiteral(pattern) {
-    return pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-function buildRegexPattern(pattern, options) {
-    const escaped = options.isLiteral ? escapeLiteral(pattern) : pattern;
-    return options.wholeWord ? `\\b${escaped}\\b` : escaped;
-}
-function validatePattern(pattern, options) {
-    if (options.isLiteral && pattern.length === 0)
-        return;
-    if (options.isLiteral && !options.wholeWord)
-        return;
-    const final = buildRegexPattern(pattern, options);
-    if (!safeRegex(final)) {
-        throw new Error(`Potentially unsafe regular expression (ReDoS risk): ${pattern}`);
-    }
-}
-function buildLiteralMatcher(pattern, options) {
-    if (!options.caseSensitive) {
-        const final = escapeLiteral(pattern);
-        const regex = new RegExp(final, 'gi');
-        return (line) => countRegexLineMatches(regex, line);
-    }
-    // Fast path for case-sensitive literal
-    const needle = pattern;
-    if (needle.length === 0)
-        return () => 0;
-    return (line) => {
-        if (line.length === 0)
-            return 0;
-        let count = 0;
-        let pos = line.indexOf(needle);
-        while (pos !== -1) {
-            count++;
-            pos = line.indexOf(needle, pos + needle.length);
-        }
-        return count;
-    };
-}
-function buildRegexMatcher(final, caseSensitive) {
-    const regex = new RE2(final, caseSensitive ? 'g' : 'gi');
-    return (line) => countRegexLineMatches(regex, line);
-}
-export function buildMatcher(pattern, options) {
-    if (options.isLiteral && pattern.length === 0)
-        return () => 0;
-    if (options.isLiteral && !options.wholeWord) {
-        // fast path for simple literal search
-        return buildLiteralMatcher(pattern, options);
-    }
-    const final = buildRegexPattern(pattern, options);
-    validatePattern(pattern, options); // Re-validate to be safe
-    return buildRegexMatcher(final, options.caseSensitive);
-}
 /**
  * Manages a sliding window of lines and pending context-after buffers.
  */
@@ -562,13 +493,6 @@ function processScanResult(winner, summary, matches, maxResults) {
         }
     }
 }
-function reportSearchProgress(onProgress, current, total, force = false) {
-    if (!onProgress || current === 0)
-        return;
-    if (!force && current % 25 !== 0)
-        return;
-    onProgress({ current, total });
-}
 async function waitForWinner(pending) {
     const raceCandidates = [];
     for (const task of pending) {
@@ -659,7 +583,7 @@ async function searchSingleFile(details, opts, pattern, signal) {
 async function searchDirectory(details, opts, pattern, signal, onProgress) {
     const root = await validateExistingDirectory(details.resolvedPath, signal);
     const rootDirectories = [root];
-    const stream = globEntries({
+    const stream = globEntries(buildGlobOptions({
         cwd: root,
         pattern: opts.filePattern,
         excludePatterns: opts.excludePatterns,
@@ -670,7 +594,7 @@ async function searchDirectory(details, opts, pattern, signal, onProgress) {
         onlyFiles: true,
         stats: false,
         suppressErrors: true,
-    });
+    }));
     async function* fileGenerator() {
         let scanned = 0;
         for await (const entry of stream) {
@@ -686,10 +610,17 @@ async function searchDirectory(details, opts, pattern, signal, onProgress) {
             if (isSensitivePath(entry.path, normalized))
                 continue;
             scanned++;
-            reportSearchProgress(onProgress, scanned, opts.maxFilesScanned);
+            reportPeriodicProgress(onProgress, scanned, {
+                total: opts.maxFilesScanned,
+                throttleModulo: 25,
+            });
             yield { resolvedPath: normalized, requestedPath: entry.path };
         }
-        reportSearchProgress(onProgress, scanned, opts.maxFilesScanned, true);
+        reportPeriodicProgress(onProgress, scanned, {
+            total: opts.maxFilesScanned,
+            throttleModulo: 25,
+            force: true,
+        });
     }
     const summary = createScanSummary();
     const resolvedStream = fileGenerator();
@@ -725,17 +656,18 @@ export async function searchContent(basePath, pattern, options = {}) {
     if (typeof pattern !== 'string')
         throw new McpError(ErrorCode.E_INVALID_INPUT, 'pattern required');
     const opts = resolveOptions(options);
-    const { signal, cleanup } = createTimedAbortSignal(options.signal, opts.timeoutMs);
     try {
-        const details = await validateExistingPathDetailed(basePath, signal);
-        const stats = await withAbort(fsp.stat(details.resolvedPath), signal);
-        if (stats.isFile()) {
-            return await searchSingleFile(details, opts, pattern, signal);
-        }
-        if (!stats.isDirectory()) {
-            throw new McpError(ErrorCode.E_INVALID_INPUT, 'Path must be file or directory', basePath);
-        }
-        return await searchDirectory(details, opts, pattern, signal, options.onProgress);
+        return await withTimedAbortSignal(options.signal, opts.timeoutMs, async (signal) => {
+            const details = await validateExistingPathDetailed(basePath, signal);
+            const stats = await withAbort(fsp.stat(details.resolvedPath), signal);
+            if (stats.isFile()) {
+                return searchSingleFile(details, opts, pattern, signal);
+            }
+            if (!stats.isDirectory()) {
+                throw new McpError(ErrorCode.E_INVALID_INPUT, 'Path must be file or directory', basePath);
+            }
+            return searchDirectory(details, opts, pattern, signal, options.onProgress);
+        });
     }
     catch (error) {
         if (isTimeoutLikeError(error)) {
@@ -743,7 +675,4 @@ export async function searchContent(basePath, pattern, options = {}) {
         }
         throw error;
     }
-    finally {
-        cleanup();
-    }
 }

package/dist/lib/file-operations/search-files.js

@@ -1,11 +1,13 @@
 import * as path from 'node:path';
 import { DEFAULT_SEARCH_MAX_FILES, DEFAULT_SEARCH_TIMEOUT_MS, } from '../constants.js';
-import { createTimedAbortSignal } from '../fs-helpers.js';
+import { withTimedAbortSignal } from '../fs-helpers.js';
 import { isSensitivePath } from '../path-policy.js';
 import { isPathWithinDirectories, normalizePath, validateExistingDirectory, validateExistingPathDetailed, } from '../path-validation.js';
+import { reportPeriodicProgress } from '../progress-reporting.js';
 import { compareOptionalNumberDesc, compareStringValues, isEntryAccessibleByType, needsStatsForSort, resolveEntryType, resolveStopReason, stableSortByDerivedString, withOptionalStoppedReason, } from './common.js';
 import { isIgnoredByGitignore, loadRootGitignore } from './gitignore.js';
 import { globEntries } from './glob-engine.js';
+import { buildGlobOptions } from './glob-helpers.js';
 // Internal default for find tool - not exposed to MCP users
 const INTERNAL_MAX_RESULTS = 1000;
 function normalizeOptions(options) {
@@ -68,7 +70,7 @@ function createCollectState() {
     };
 }
 function buildSearchStream(root, pattern, excludePatterns, normalized, needsStats) {
-    const options = {
+    const options = buildGlobOptions({
         cwd: root,
         pattern,
         excludePatterns,
@@ -78,10 +80,10 @@ function buildSearchStream(root, pattern, excludePatterns, normalized, needsStat
         followSymbolicLinks: false,
         onlyFiles: true,
         stats: needsStats,
-    };
-    if (normalized.maxDepth !== undefined) {
-        options.maxDepth = normalized.maxDepth;
-    }
+        ...(normalized.maxDepth !== undefined
+            ? { maxDepth: normalized.maxDepth }
+            : {}),
+    });
     return globEntries(options);
 }
 function buildCollectResult(state) {
@@ -103,19 +105,15 @@ function handleEntry(entry, entryType, needsStats, normalized, state) {
         state.stoppedReason = 'maxResults';
     }
 }
-function reportSearchFilesProgress(onProgress, current, total, force = false) {
-    if (!onProgress || current === 0)
-        return;
-    if (!force && current % 25 !== 0)
-        return;
-    onProgress({ current, total });
-}
 async function collectFromStream(stream, root, rootDirectories, gitignoreMatcher, normalized, needsStats, state, signal, accessDeps, onProgress) {
     for await (const entry of stream) {
         if (shouldStopCollecting(state, normalized, signal))
             break;
         state.filesScanned++;
-        reportSearchFilesProgress(onProgress, state.filesScanned, normalized.maxFilesScanned);
+        reportPeriodicProgress(onProgress, state.filesScanned, {
+            total: normalized.maxFilesScanned,
+            throttleModulo: 25,
+        });
         if (isEntryIgnoredByGitignore(gitignoreMatcher, root, entry.path, entry.relativePath)) {
             continue;
         }
@@ -132,7 +130,11 @@ async function collectFromStream(stream, root, rootDirectories, gitignoreMatcher
         if (state.truncated)
             break;
     }
-    reportSearchFilesProgress(onProgress, state.filesScanned, normalized.maxFilesScanned, true);
+    reportPeriodicProgress(onProgress, state.filesScanned, {
+        total: normalized.maxFilesScanned,
+        throttleModulo: 25,
+        force: true,
+    });
 }
 function isEntryIgnoredByGitignore(matcher, root, entryPath, relativePath) {
     if (!matcher)
@@ -201,9 +203,8 @@ async function runSearchFiles(root, pattern, excludePatterns, normalized, signal
 }
 export async function searchFiles(basePath, pattern, excludePatterns = [], options = {}) {
     const normalized = normalizeOptions(options);
-    const { signal, cleanup } = createTimedAbortSignal(options.signal, normalized.timeoutMs);
-    const root = await validateExistingDirectory(basePath, signal);
-    try {
+    return withTimedAbortSignal(options.signal, normalized.timeoutMs, async (signal) => {
+        const root = await validateExistingDirectory(basePath, signal);
         const { results, summary } = await runSearchFiles(root, pattern, excludePatterns, normalized, signal, options.onProgress);
         return {
             basePath: root,
@@ -211,8 +212,5 @@ export async function searchFiles(basePath, pattern, excludePatterns = [], optio
             results,
             summary,
         };
-    }
-    finally {
-        cleanup();
-    }
+    });
 }

package/dist/lib/file-operations/search-matcher.d.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+export declare const MatcherOptionsSchema: z.ZodObject<{
+    caseSensitive: z.ZodBoolean;
+    wholeWord: z.ZodBoolean;
+    isLiteral: z.ZodBoolean;
+}, z.core.$strict>;
+export type MatcherOptions = z.infer<typeof MatcherOptionsSchema>;
+export type Matcher = (line: string) => number;
+export declare function validatePattern(pattern: string, options: MatcherOptions): void;
+export declare function buildMatcher(pattern: string, options: MatcherOptions): Matcher;

package/dist/lib/file-operations/search-matcher.js

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import RE2 from 're2';
+import safeRegex from 'safe-regex2';
+export const MatcherOptionsSchema = z.strictObject({
+    caseSensitive: z.boolean(),
+    wholeWord: z.boolean(),
+    isLiteral: z.boolean(),
+});
+function countRegexLineMatches(regex, line) {
+    regex.lastIndex = 0;
+    let count = 0;
+    while (regex.exec(line) !== null) {
+        count++;
+        if (regex.lastIndex === 0)
+            regex.lastIndex++;
+    }
+    return count;
+}
+function escapeLiteral(pattern) {
+    return pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function buildRegexPattern(pattern, options) {
+    const escaped = options.isLiteral ? escapeLiteral(pattern) : pattern;
+    return options.wholeWord ? `\\b${escaped}\\b` : escaped;
+}
+export function validatePattern(pattern, options) {
+    if (options.isLiteral && pattern.length === 0)
+        return;
+    if (options.isLiteral && !options.wholeWord)
+        return;
+    const final = buildRegexPattern(pattern, options);
+    if (!safeRegex(final)) {
+        throw new Error(`Potentially unsafe regular expression (ReDoS risk): ${pattern}`);
+    }
+}
+function buildLiteralMatcher(pattern, options) {
+    if (!options.caseSensitive) {
+        const final = escapeLiteral(pattern);
+        const regex = new RegExp(final, 'gi');
+        return (line) => countRegexLineMatches(regex, line);
+    }
+    // Fast path for case-sensitive literal
+    const needle = pattern;
+    if (needle.length === 0)
+        return () => 0;
+    return (line) => {
+        if (line.length === 0)
+            return 0;
+        let count = 0;
+        let pos = line.indexOf(needle);
+        while (pos !== -1) {
+            count++;
+            pos = line.indexOf(needle, pos + needle.length);
+        }
+        return count;
+    };
+}
+function buildRegexMatcher(final, caseSensitive) {
+    const regex = new RE2(final, caseSensitive ? 'g' : 'gi');
+    return (line) => countRegexLineMatches(regex, line);
+}
+export function buildMatcher(pattern, options) {
+    if (options.isLiteral && pattern.length === 0)
+        return () => 0;
+    if (options.isLiteral && !options.wholeWord) {
+        // fast path for simple literal search
+        return buildLiteralMatcher(pattern, options);
+    }
+    const final = buildRegexPattern(pattern, options);
+    validatePattern(pattern, options); // Re-validate to be safe
+    return buildRegexMatcher(final, options.caseSensitive);
+}

package/dist/lib/file-operations/search-worker.js

@@ -2,7 +2,9 @@ import { parentPort, threadId, workerData } from 'node:worker_threads';
 import { formatUnknownErrorMessage } from '../errors.js';
 import { isProbablyBinary } from '../fs-helpers.js';
 import { startPerfMeasure } from '../observability.js';
-import { buildMatcher, scanFileInWorker } from './search-content.js';
+import { scanFileInWorker } from './search-content.js';
+import { buildMatcher } from './search-matcher.js';
+import {} from './search-matcher.js';
 const matcherCache = new Map();
 const MAX_MATCHER_CACHE_SIZE = 100;
 function getMatcherCacheKey(pattern, options) {

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

@@ -1,6 +1,6 @@
 import * as path from 'node:path';
 import { DEFAULT_EXCLUDE_PATTERNS, DEFAULT_SEARCH_TIMEOUT_MS, } from '../constants.js';
-import { createTimedAbortSignal } from '../fs-helpers.js';
+import { withTimedAbortSignal } from '../fs-helpers.js';
 import { toPosixPath } from '../path-format.js';
 import { isSensitivePath } from '../path-policy.js';
 import { isPathWithinDirectories, normalizePath, validateExistingDirectory, validateExistingPathDetailed, } from '../path-validation.js';
@@ -194,17 +194,16 @@ export function formatTreeAscii(tree) {
 }
 export async function treeDirectory(dirPath, options = {}) {
     const normalized = normalizeOptions(options);
-    const { signal, cleanup } = createTimedAbortSignal(options.signal, normalized.timeoutMs);
-    const root = await validateExistingDirectory(dirPath, signal);
-    const rootNormalized = normalizePath(root);
-    const rootDirectories = [rootNormalized];
-    const accessDeps = {
-        normalizePath,
-        isPathWithinDirectories,
-        isSensitivePath,
-        validateSymlinkPath: validateExistingPathDetailed,
-    };
-    try {
+    return withTimedAbortSignal(options.signal, normalized.timeoutMs, async (signal) => {
+        const root = await validateExistingDirectory(dirPath, signal);
+        const rootNormalized = normalizePath(root);
+        const rootDirectories = [rootNormalized];
+        const accessDeps = {
+            normalizePath,
+            isPathWithinDirectories,
+            isSensitivePath,
+            validateSymlinkPath: validateExistingPathDetailed,
+        };
         const excludePatterns = normalized.includeIgnored
             ? []
             : DEFAULT_EXCLUDE_PATTERNS;
@@ -262,8 +261,5 @@ export async function treeDirectory(dirPath, options = {}) {
             truncated,
             totalEntries,
         };
-    }
-    finally {
-        cleanup();
-    }
+    });
 }

package/dist/lib/fs-helpers.d.ts

@@ -7,6 +7,7 @@ export declare function createTimedAbortSignal(baseSignal: AbortSignal | undefin
     signal: AbortSignal;
     cleanup: () => void;
 };
+export declare function withTimedAbortSignal<T>(baseSignal: AbortSignal | undefined, timeoutMs: number | undefined, run: (signal: AbortSignal) => Promise<T>): Promise<T>;
 interface ParallelResult<R> {
     results: R[];
     errors: {

package/dist/lib/fs-helpers.js

@@ -110,6 +110,15 @@ export function createTimedAbortSignal(baseSignal, timeoutMs) {
     }
     return createNoopSignal();
 }
+export async function withTimedAbortSignal(baseSignal, timeoutMs, run) {
+    const { signal, cleanup } = createTimedAbortSignal(baseSignal, timeoutMs);
+    try {
+        return await run(signal);
+    }
+    finally {
+        cleanup();
+    }
+}
 function createNoopSignal() {
     return { signal: SHARED_NOOP_SIGNAL, cleanup: () => { } };
 }

package/dist/lib/option-utils.d.ts

@@ -0,0 +1,3 @@
+export declare function mergeOptions<T extends object>(defaults: T, overrides: Partial<T>): T;
+export declare function omitOptionKeys<T extends object, K extends keyof T>(input: T, keys: readonly K[]): Omit<T, K>;
+export declare function setIfDefined<T extends object, K extends keyof T>(target: T, key: K, value: T[K] | undefined): void;

package/dist/lib/option-utils.js

@@ -0,0 +1,15 @@
+export function mergeOptions(defaults, overrides) {
+    return { ...defaults, ...overrides };
+}
+export function omitOptionKeys(input, keys) {
+    const output = { ...input };
+    for (const key of keys) {
+        Reflect.deleteProperty(output, key);
+    }
+    return output;
+}
+export function setIfDefined(target, key, value) {
+    if (value !== undefined) {
+        target[key] = value;
+    }
+}

package/dist/lib/path-validation.d.ts

@@ -8,6 +8,7 @@ import { McpError } from './errors.js';
  */
 export declare function normalizePath(p: string): string;
 export declare function getAllowedDirectories(): string[];
+export declare function isAllowedDirectoryRoot(normalizedPath: string): boolean;
 export declare function isPathWithinDirectories(normalizedPath: string, allowedDirs: readonly string[]): boolean;
 export declare function setAllowedDirectoriesResolved(dirs: readonly string[], signal?: AbortSignal): Promise<void>;
 export declare function getReservedDeviceNameForPath(requestedPath: string): string | undefined;

package/dist/lib/path-validation.js

@@ -124,6 +124,13 @@ function setAllowedDirectoriesState(primary, expanded) {
 export function getAllowedDirectories() {
     return [...allowedDirectoriesExpanded];
 }
+export function isAllowedDirectoryRoot(normalizedPath) {
+    for (const dir of allowedDirectoriesExpanded) {
+        if (isSamePath(normalizedPath, dir))
+            return true;
+    }
+    return false;
+}
 function getAllowedDirectoriesForRelativeResolution() {
     return allowedDirectoriesPrimary.length > 0
         ? allowedDirectoriesPrimary

package/dist/lib/progress-reporting.d.ts

@@ -0,0 +1,11 @@
+export interface ProgressPayload {
+    current: number;
+    total?: number;
+}
+export type ProgressCallback = ((progress: ProgressPayload) => void) | undefined;
+export interface PeriodicProgressOptions {
+    total?: number;
+    throttleModulo?: number;
+    force?: boolean;
+}
+export declare function reportPeriodicProgress(onProgress: ProgressCallback, current: number, options?: PeriodicProgressOptions): void;

package/dist/lib/progress-reporting.js

@@ -0,0 +1,13 @@
+export function reportPeriodicProgress(onProgress, current, options = {}) {
+    if (!onProgress || current === 0)
+        return;
+    const throttleModulo = options.throttleModulo ?? 1;
+    const force = options.force ?? false;
+    if (!force && throttleModulo > 1 && current % throttleModulo !== 0) {
+        return;
+    }
+    onProgress({
+        current,
+        ...(options.total !== undefined ? { total: options.total } : {}),
+    });
+}

package/dist/tools/apply-patch.js

@@ -48,6 +48,9 @@ async function handleApplyPatch(args, signal) {
     if (patched === false) {
         throw new McpError(ErrorCode.E_INVALID_INPUT, 'Patch application failed. The file content may have changed or patch context is insufficient. Generate a fresh patch via diff_files against the current file, then retry. If differences are minor, enable fuzzy matching with the fuzzFactor parameter.');
     }
+    if (patched === content) {
+        throw new McpError(ErrorCode.E_INVALID_INPUT, 'Patch had no effect — the file content is unchanged after applying. The patch may not match the current file content. Generate a fresh patch via diff_files and retry.');
+    }
     if (args.dryRun) {
         return buildToolResponse('Dry run successful. Patch can be applied.', {
             ok: true,

package/dist/tools/calculate-hash.js

@@ -8,8 +8,9 @@ import { isIgnoredByGitignore, loadRootGitignore, } from '../lib/file-operations
 import { globEntries } from '../lib/file-operations/glob-engine.js';
 import { assertNotAborted, withAbort } from '../lib/fs-helpers.js';
 import { validateExistingPath } from '../lib/path-validation.js';
+import { reportPeriodicProgress } from '../lib/progress-reporting.js';
 import { CalculateHashInputSchema, CalculateHashOutputSchema, } from '../schemas.js';
-import { buildToolErrorResponse, buildToolResponse, createToolProgressSession, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildToolErrorResponse, buildToolResponse, createToolProgressSession, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, resolveFinalProgressCurrent, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 const WINDOWS_PATH_SEPARATOR = /\\/gu;
 export const CALCULATE_HASH_TOOL = {
@@ -54,13 +55,6 @@ function updateCompositeHash(hasher, pathLengthBytes, relativePath, fileHash) {
     hasher.update(relativePathBytes);
     hasher.update(fileHash);
 }
-function reportHashProgress(onProgress, current, force = false) {
-    if (!onProgress || current === 0)
-        return;
-    if (!force && current % 25 !== 0)
-        return;
-    onProgress({ current });
-}
 async function hashDirectory(dirPath, options = {}) {
     const { signal, onProgress } = options;
     const gitignoreMatcher = await loadRootGitignore(dirPath, signal);
@@ -102,9 +96,12 @@ async function hashDirectory(dirPath, options = {}) {
         }));
         entries.push(...batchResults);
         filesHashed += batchResults.length;
-        reportHashProgress(onProgress, filesHashed);
+        reportPeriodicProgress(onProgress, filesHashed, { throttleModulo: 25 });
     }
-    reportHashProgress(onProgress, filesHashed, true);
+    reportPeriodicProgress(onProgress, filesHashed, {
+        throttleModulo: 25,
+        force: true,
+    });
     assertNotAborted(signal);
     // Sort by path with byte-wise semantics for deterministic ordering.
     entries.sort(comparePaths);
@@ -141,7 +138,10 @@ async function handleCalculateHash(args, signal, onProgress) {
     else {
         // Hash single file
         const hash = await hashFile(validPath, 'hex', signal);
-        reportHashProgress(onProgress, 1, true);
+        reportPeriodicProgress(onProgress, 1, {
+            throttleModulo: 25,
+            force: true,
+        });
         return buildToolResponse(hash, {
             ok: true,
             path: validPath,
@@ -171,7 +171,7 @@ export function registerCalculateHashTool(server, options = {}) {
                 const result = await handleCalculateHash(args, signal, progressWithMessage);
                 const sc = result.structuredContent;
                 const totalFiles = sc.ok ? (sc.fileCount ?? 1) : 1;
-                const finalCurrent = Math.max(totalFiles + 1, progress.getCurrent() + 1);
+                const finalCurrent = resolveFinalProgressCurrent(progress, totalFiles + 1);
                 let suffix;
                 if (!sc.ok) {
                     suffix = 'failed';

package/dist/tools/delete-file.js

@@ -1,8 +1,8 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
-import { ErrorCode, isNodeError } from '../lib/errors.js';
+import { ErrorCode, isNodeError, McpError } from '../lib/errors.js';
 import { withAbort } from '../lib/fs-helpers.js';
-import { validatePathForWrite } from '../lib/path-validation.js';
+import { isAllowedDirectoryRoot, validatePathForWrite, } from '../lib/path-validation.js';
 import { DeleteFileInputSchema, DeleteFileOutputSchema } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
@@ -20,6 +20,9 @@ export const DELETE_FILE_TOOL = {
 };
 async function handleDeleteFile(args, signal) {
     const validPath = await validatePathForWrite(args.path, signal);
+    if (isAllowedDirectoryRoot(validPath)) {
+        throw new McpError(ErrorCode.E_ACCESS_DENIED, `Deleting a workspace root directory is not allowed: ${args.path}`);
+    }
     let stats;
     try {
         stats = await withAbort(fs.lstat(validPath), signal);

package/dist/tools/read-multiple.js

@@ -3,7 +3,7 @@ import { DEFAULT_READ_MANY_MAX_TOTAL_SIZE, DEFAULT_SEARCH_TIMEOUT_MS, } from '..
 import { ErrorCode } from '../lib/errors.js';
 import { readMultipleFiles } from '../lib/file-operations/read-multiple-files.js';
 import { ReadMultipleFilesInputSchema, ReadMultipleFilesOutputSchema, } from '../schemas.js';
-import { buildBatchPathContext, buildResourceLink, buildToolErrorResponse, buildToolResponse, createToolProgressSession, executeToolWithDiagnostics, maybeExternalizeTextContent, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildBatchCompletionSuffix, buildBatchPathContext, buildResourceLink, buildToolErrorResponse, buildToolResponse, createBatchProgressCallbacks, executeToolWithDiagnostics, maybeExternalizeTextContent, READ_ONLY_TOOL_ANNOTATIONS, resolveFinalProgressCurrent, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 export const READ_MULTIPLE_FILES_TOOL = {
     name: 'read_many',
@@ -20,23 +20,6 @@ export const READ_MULTIPLE_FILES_TOOL = {
         'Per-file `truncationReason` can be `head`, `range`, or `externalized`.',
     ],
 };
-function buildReadManyCompletionSuffix(summary) {
-    const total = summary?.total ?? 0;
-    const failed = summary?.failed ?? 0;
-    const succeeded = summary?.succeeded ?? 0;
-    if (failed) {
-        return `${succeeded}/${total} read, ${failed} failed`;
-    }
-    const label = total === 1 ? 'file' : 'files';
-    return `${total} ${label} read`;
-}
-function createReadManyProgressCallbacks(extra, context, totalPaths) {
-    const progress = createToolProgressSession(extra, `🕮 read_many: ${context}`);
-    const onReadComplete = () => {
-        progress.increment((current) => `🕮 read_many: ${context} [${current}/${totalPaths} read]`);
-    };
-    return { progress, onReadComplete };
-}
 function toStructuredReadManyResult(result) {
     const structured = {
         path: result.path,
@@ -152,13 +135,18 @@ export function registerReadMultipleFilesTool(server, options = {}) {
             context: { path: primaryPath },
             run: async (signal) => {
                 const context = buildBatchPathContext(args.paths, 'files');
-                const { progress, onReadComplete } = createReadManyProgressCallbacks(extra, context, args.paths.length);
+                const { progress, onItemComplete } = createBatchProgressCallbacks(extra, {
+                    toolLabel: '🕮 read_many',
+                    context,
+                    totalItems: args.paths.length,
+                    itemVerb: 'read',
+                });
                 try {
-                    const result = await handleReadMultipleFiles(args, signal, options.resourceStore, onReadComplete);
+                    const result = await handleReadMultipleFiles(args, signal, options.resourceStore, onItemComplete);
                     const sc = result.structuredContent;
-                    const suffix = buildReadManyCompletionSuffix(sc.summary);
+                    const suffix = buildBatchCompletionSuffix(sc.summary, 'files read', 'file read');
                     const total = sc.summary?.total ?? 0;
-                    const finalCurrent = Math.max(total, progress.getCurrent() + 1);
+                    const finalCurrent = resolveFinalProgressCurrent(progress, total);
                     progress.complete(`🕮 read_many: ${context} • ${suffix}`, finalCurrent);
                     return result;
                 }

package/dist/tools/replace-in-files.js

@@ -8,8 +8,9 @@ import { ErrorCode, formatUnknownErrorMessage, McpError, } from '../lib/errors.j
 import { globEntries } from '../lib/file-operations/glob-engine.js';
 import { atomicWriteFile, withAbort } from '../lib/fs-helpers.js';
 import { validateExistingPath, validatePathForWrite, } from '../lib/path-validation.js';
+import { reportPeriodicProgress } from '../lib/progress-reporting.js';
 import { SearchAndReplaceInputSchema, SearchAndReplaceOutputSchema, } from '../schemas.js';
-import { buildToolErrorResponse, buildToolResponse, createToolProgressSession, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildToolErrorResponse, buildToolResponse, createToolProgressSession, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, resolveFinalProgressCurrent, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 export const SEARCH_AND_REPLACE_TOOL = {
     name: 'search_and_replace',
@@ -204,13 +205,6 @@ function createReplacementMatcher(args) {
     }
     return createLiteralReplacementMatcher(args.searchPattern);
 }
-function reportReplaceProgress(onProgress, current, force = false) {
-    if (current === 0)
-        return;
-    if (!force && current % 25 !== 0)
-        return;
-    onProgress({ current });
-}
 export async function handleSearchAndReplace(args, signal, onProgress = () => { }) {
     const maxFileSize = MAX_TEXT_FILE_SIZE;
     const root = await resolveSearchRoot(args.path, signal);
@@ -233,14 +227,19 @@ export async function handleSearchAndReplace(args, signal, onProgress = () => {
         concurrency: REPLACE_CONCURRENCY,
         onEntry: () => {
             summary.processedFiles++;
-            reportReplaceProgress(onProgress, summary.processedFiles);
+            reportPeriodicProgress(onProgress, summary.processedFiles, {
+                throttleModulo: 25,
+            });
         },
         runEntry: async (entryPath) => processEntry(entryPath, {
             dryRun: args.dryRun,
             returnDiff: args.returnDiff ?? false,
         }, args.replacement, matcher, maxFileSize, signal, summary),
     });
-    reportReplaceProgress(onProgress, summary.processedFiles, true);
+    reportPeriodicProgress(onProgress, summary.processedFiles, {
+        throttleModulo: 25,
+        force: true,
+    });
     const failureSuffix = summary.failedFiles > 0 ? ` (${summary.failedFiles} failed)` : '';
     return buildToolResponse(`Found ${summary.totalMatches} matches in ${summary.filesChanged} files${failureSuffix}.${args.dryRun ? ' (Dry run)' : ''}`, {
         ok: true,
@@ -279,7 +278,7 @@ export function registerSearchAndReplaceTool(server, options = {}) {
             try {
                 const result = await handleSearchAndReplace(args, signal, progressWithMessage);
                 const sc = result.structuredContent;
-                const finalCurrent = Math.max((sc.processedFiles ?? 0) + 1, progress.getCurrent() + 1);
+                const finalCurrent = resolveFinalProgressCurrent(progress, (sc.processedFiles ?? 0) + 1);
                 const matchWord = (sc.matches ?? 0) === 1 ? 'match' : 'matches';
                 const fileWord = (sc.filesChanged ?? 0) === 1 ? 'file' : 'files';
                 let endSuffix = `${sc.matches ?? 0} ${matchWord} in ${sc.filesChanged ?? 0} ${fileWord}`;

package/dist/tools/search-content.js

@@ -5,7 +5,7 @@ import { DEFAULT_EXCLUDE_PATTERNS } from '../lib/constants.js';
 import { ErrorCode, formatUnknownErrorMessage, McpError, } from '../lib/errors.js';
 import { searchContent } from '../lib/file-operations/search-content.js';
 import { SearchContentInputSchema, SearchContentOutputSchema, } from '../schemas.js';
-import { buildResourceLink, buildToolErrorResponse, buildToolResponse, createToolProgressSession, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildResourceLink, buildToolErrorResponse, buildToolResponse, createToolProgressSession, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, resolveFinalProgressCurrent, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 const MAX_INLINE_MATCHES = parseInt(process.env['FS_CONTEXT_MAX_INLINE_MATCHES'] ?? '', 10) || 50;
 export const SEARCH_CONTENT_TOOL = {
@@ -242,7 +242,7 @@ export function registerSearchContentTool(server, options = {}) {
                         suffix += ' [truncated — max files]';
                     }
                 }
-                const finalCurrent = Math.max((sc.filesScanned ?? 0) + 1, progress.getCurrent() + 1);
+                const finalCurrent = resolveFinalProgressCurrent(progress, (sc.filesScanned ?? 0) + 1);
                 progress.complete(`🔎︎ grep: ${pattern} • ${suffix}`, finalCurrent);
                 return result;
             }

package/dist/tools/shared.d.ts

@@ -123,7 +123,18 @@ export interface ToolProgressSession {
     fail: (message: string, minimumCurrent?: number) => void;
     getCurrent: () => number;
 }
+export interface BatchProgressCallbacks {
+    progress: ToolProgressSession;
+    onItemComplete: () => void;
+}
 export declare function createToolProgressSession(extra: ToolExtra, startMessage: string): ToolProgressSession;
+export declare function createBatchProgressCallbacks(extra: ToolExtra, params: {
+    toolLabel: string;
+    context: string;
+    totalItems: number;
+    itemVerb: string;
+}): BatchProgressCallbacks;
+export declare function resolveFinalProgressCurrent(progress: ToolProgressSession, ...candidates: number[]): number;
 export declare function wrapToolHandler<Args, Result>(handler: (args: Args, extra: ToolExtra) => Promise<ToolResult<Result>>, options: {
     guard?: (() => boolean) | undefined;
     progressMessage?: (args: Args) => string;
@@ -142,3 +153,8 @@ export declare function resolvePathOrRoot(pathValue: string | undefined): string
 export declare function encodeOffsetCursor(offset: number): string;
 export declare function decodeOffsetCursor(cursor: string): number;
 export declare function buildBatchPathContext(paths: readonly string[], unitLabel?: string): string;
+export declare function buildBatchCompletionSuffix(summary: {
+    total?: number;
+    failed?: number;
+    succeeded?: number;
+} | undefined, successWord: string, singularWord?: string): string;

package/dist/tools/shared.js

@@ -293,6 +293,15 @@ export function createToolProgressSession(extra, startMessage) {
             cursor = value;
         return cursor;
     };
+    const finishProgress = (message, minimumCurrent) => {
+        const finalCurrent = Math.max(cursor + 1, minimumCurrent ?? 1, 1);
+        notifyProgress(extra, {
+            current: finalCurrent,
+            total: finalCurrent,
+            ...(message !== undefined ? { message } : {}),
+        });
+        cursor = finalCurrent;
+    };
     return {
         update: ({ current, total, message }) => {
             const normalized = setCursor(current);
@@ -309,27 +318,27 @@ export function createToolProgressSession(extra, startMessage) {
                 message: messageForCurrent(next),
             });
         },
-        complete: (message, minimumCurrent) => {
-            const finalCurrent = Math.max(cursor + 1, minimumCurrent ?? 1, 1);
-            notifyProgress(extra, {
-                current: finalCurrent,
-                total: finalCurrent,
-                message,
-            });
-            cursor = finalCurrent;
-        },
-        fail: (message, minimumCurrent) => {
-            const finalCurrent = Math.max(cursor + 1, minimumCurrent ?? 1, 1);
-            notifyProgress(extra, {
-                current: finalCurrent,
-                total: finalCurrent,
-                message,
-            });
-            cursor = finalCurrent;
-        },
+        complete: finishProgress,
+        fail: finishProgress,
         getCurrent: () => cursor,
     };
 }
+export function createBatchProgressCallbacks(extra, params) {
+    const progress = createToolProgressSession(extra, `${params.toolLabel}: ${params.context}`);
+    const onItemComplete = () => {
+        progress.increment((current) => `${params.toolLabel}: ${params.context} [${current}/${params.totalItems} ${params.itemVerb}]`);
+    };
+    return { progress, onItemComplete };
+}
+export function resolveFinalProgressCurrent(progress, ...candidates) {
+    let finalCurrent = progress.getCurrent() + 1;
+    for (const candidate of candidates) {
+        if (candidate > finalCurrent) {
+            finalCurrent = candidate;
+        }
+    }
+    return finalCurrent;
+}
 async function withProgress(message, extra, run, getCompletionMessage) {
     if (!canReportProgress(extra)) {
         return run();
@@ -430,3 +439,13 @@ export function buildBatchPathContext(paths, unitLabel = 'paths') {
         : '';
     return `${paths.length} ${normalizedLabel} [${first}${extraPaths}]`;
 }
+export function buildBatchCompletionSuffix(summary, successWord, singularWord) {
+    const total = summary?.total ?? 0;
+    const failed = summary?.failed ?? 0;
+    const succeeded = summary?.succeeded ?? 0;
+    if (failed) {
+        return `${succeeded}/${total} ${successWord}, ${failed} failed`;
+    }
+    const word = total === 1 && singularWord ? singularWord : successWord;
+    return `${total} ${word}`;
+}

package/dist/tools/stat-many.js

@@ -3,7 +3,7 @@ import { DEFAULT_SEARCH_TIMEOUT_MS } from '../lib/constants.js';
 import { ErrorCode } from '../lib/errors.js';
 import { getMultipleFileInfo } from '../lib/file-operations/file-info.js';
 import { GetMultipleFileInfoInputSchema, GetMultipleFileInfoOutputSchema, } from '../schemas.js';
-import { buildBatchPathContext, buildFileInfoPayload, buildToolErrorResponse, buildToolResponse, createToolProgressSession, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildBatchCompletionSuffix, buildBatchPathContext, buildFileInfoPayload, buildToolErrorResponse, buildToolResponse, createBatchProgressCallbacks, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, resolveFinalProgressCurrent, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 export const GET_MULTIPLE_FILE_INFO_TOOL = {
     name: 'stat_many',
@@ -15,22 +15,6 @@ export const GET_MULTIPLE_FILE_INFO_TOOL = {
     taskSupport: 'optional',
     nuances: ['Use before read/search when file size/type uncertainty exists.'],
 };
-function buildStatManyCompletionSuffix(summary) {
-    const total = summary?.total ?? 0;
-    const failed = summary?.failed ?? 0;
-    const succeeded = summary?.succeeded ?? 0;
-    if (failed) {
-        return `${succeeded}/${total} OK, ${failed} failed`;
-    }
-    return `${total} OK`;
-}
-function createStatManyProgressCallbacks(extra, context, totalPaths) {
-    const progress = createToolProgressSession(extra, `🕮 stat_many: ${context}`);
-    const onProgress = () => {
-        progress.increment((current) => `🕮 stat_many: ${context} [${current}/${totalPaths} scanned]`);
-    };
-    return { progress, onProgress };
-}
 function formatFileInfoDetail(info) {
     const lines = [
         `${info.name} (${info.type})`,
@@ -90,13 +74,18 @@ export function registerGetMultipleFileInfoTool(server, options = {}) {
             context: { path: primaryPath },
             run: async (signal) => {
                 const context = buildBatchPathContext(args.paths);
-                const { progress, onProgress } = createStatManyProgressCallbacks(extra, context, args.paths.length);
+                const { progress, onItemComplete } = createBatchProgressCallbacks(extra, {
+                    toolLabel: '🕮 stat_many',
+                    context,
+                    totalItems: args.paths.length,
+                    itemVerb: 'scanned',
+                });
                 try {
-                    const result = await handleGetMultipleFileInfo(args, signal, onProgress);
+                    const result = await handleGetMultipleFileInfo(args, signal, onItemComplete);
                     const sc = result.structuredContent;
-                    const suffix = buildStatManyCompletionSuffix(sc.summary);
+                    const suffix = buildBatchCompletionSuffix(sc.summary, 'OK');
                     const total = sc.summary?.total ?? 0;
-                    const finalCurrent = Math.max(total, progress.getCurrent() + 1);
+                    const finalCurrent = resolveFinalProgressCurrent(progress, total);
                     progress.complete(`🕮 stat_many: ${context} • ${suffix}`, finalCurrent);
                     return result;
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@j0hanz/filesystem-mcp",
-  "version": "1.7.3",
+  "version": "1.8.0",
   "mcpName": "io.github.j0hanz/filesystem-mcp",
   "description": "MCP Server that enables LLMs to interact with the local filesystem.",
   "type": "module",
@@ -35,8 +35,11 @@
     "type-check:diagnostics": "tsc --noEmit --extendedDiagnostics",
     "type-check:trace": "node -e \"require('fs').rmSync('.ts-trace',{recursive:true,force:true})\" && tsc --noEmit --generateTrace .ts-trace",
     "lint": "eslint .",
+    "lint:tests": "eslint src/__tests__",
     "lint:fix": "eslint . --fix",
     "test": "node scripts/tasks.mjs test",
+    "test:fast": "node --test --import tsx/esm src/__tests__/**/*.test.ts node-tests/**/*.test.ts",
+    "test:coverage": "node scripts/tasks.mjs test --coverage",
     "knip": "knip",
     "knip:fix": "knip --fix",
     "inspector": "npm run build && npx -y @modelcontextprotocol/inspector node dist/index.js ${workspaceFolder}",
@@ -71,12 +74,13 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "eslint": "^10.0.2",
     "@trivago/prettier-plugin-sort-imports": "^6.0.2",
     "@types/node": "^24",
+    "eslint": "^10.0.2",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-de-morgan": "^2.0.0",
     "eslint-plugin-depend": "^1.4.0",
+    "eslint-plugin-sonarjs": "^4.0.0",
     "eslint-plugin-unused-imports": "^4.4.1",
     "jscpd": "^4.0.8",
     "knip": "^5.85.0",