@j0hanz/filesystem-mcp 1.7.2 → 1.8.0

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

@@ -2,3 +2,45 @@ export declare function needsStatsForSort(sortBy: string): boolean;
 export declare function withOptionalStoppedReason<T extends object, R extends string>(summary: T, stoppedReason: R | undefined): T | (T & {
     stoppedReason: R;
 });
+export interface DirentLike {
+    isDirectory(): boolean;
+    isFile(): boolean;
+    isSymbolicLink(): boolean;
+}
+export type EntryType = 'file' | 'directory' | 'symlink' | 'other';
+export interface IndexedValue<T> {
+    index: number;
+    value: T;
+}
+export 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>;

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

@@ -1,9 +1,96 @@
 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 = [];
+    for (let index = 0; index < items.length; index += 1) {
+        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;
+    });
+    for (let index = 0; index < decorated.length; index += 1) {
+        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) {
+    for (const failure of options.errors) {
+        const resolvedIndex = options.resolveIndex(failure.index);
+        if (resolvedIndex === undefined)
+            continue;
+        if (resolvedIndex < 0 || resolvedIndex >= options.output.length)
+            continue;
+        options.output[resolvedIndex] = options.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;
+    }
+}

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

@@ -5,6 +5,7 @@ import { isAbortError } from '../errors.js';
 import { assertNotAborted, getFileType, isHidden, processInParallel, withAbort, } from '../fs-helpers.js';
 import { assertAllowedFileAccess } from '../path-policy.js';
 import { validateExistingPathDetailed } from '../path-validation.js';
+import { applyIndexedErrors, applyIndexedValues } from './common.js';
 const PERM_STRINGS = [
     '---',
     '--x',
@@ -95,23 +96,6 @@ async function readFileInfoInParallel(paths, options) {
         return { index, value };
     }, PARALLEL_CONCURRENCY, options.signal);
 }
-function applyResults(output, results) {
-    for (const result of results) {
-        output[result.index] = result.value;
-    }
-}
-function applyErrors(output, errors, paths) {
-    for (const failure of errors) {
-        const { index } = failure;
-        if (!isValidOutputIndex(index, output.length))
-            continue;
-        const filePath = paths[index] ?? UNKNOWN_PATH;
-        output[index] = { path: filePath, error: failure.error.message };
-    }
-}
-function isValidOutputIndex(index, length) {
-    return index >= 0 && index < length;
-}
 function calculateSummary(results) {
     let succeeded = 0;
     let failed = 0;
@@ -140,8 +124,18 @@ export async function getMultipleFileInfo(paths, options = {}) {
         output[index] = { path: paths[index] ?? UNKNOWN_PATH };
     }
     const { results, errors } = await readFileInfoInParallel(paths, options);
-    applyResults(output, results);
-    applyErrors(output, errors, paths);
+    applyIndexedValues(output, results);
+    applyIndexedErrors({
+        output,
+        errors,
+        resolveIndex: (failureIndex) => failureIndex >= 0 && failureIndex < output.length
+            ? failureIndex
+            : undefined,
+        buildValue: (resolvedIndex, error) => ({
+            path: paths[resolvedIndex] ?? UNKNOWN_PATH,
+            error: error.message,
+        }),
+    });
     return {
         results: output,
         summary: calculateSummary(output),

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

@@ -1,10 +1,5 @@
 import type { Stats } from 'node:fs';
-interface DirentLike {
-    isDirectory(): boolean;
-    isFile(): boolean;
-    isSymbolicLink(): boolean;
-}
-export declare function resolveEntryType(dirent: DirentLike): 'file' | 'directory' | 'symlink' | 'other';
+import type { DirentLike } from './common.js';
 interface GlobEntry {
     path: string;
     relativePath?: string;

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

@@ -4,15 +4,6 @@ import { glob as fsGlob } from 'node:fs/promises';
 import { getToolContextSnapshot, publishOpsTraceEnd, publishOpsTraceError, publishOpsTraceStart, shouldPublishOpsTrace, startPerfMeasure, } from '../observability.js';
 import { toPosixPath } from '../path-format.js';
 import { isRecord } from '../type-guards.js';
-export function resolveEntryType(dirent) {
-    if (dirent.isDirectory())
-        return 'directory';
-    if (dirent.isSymbolicLink())
-        return 'symlink';
-    if (dirent.isFile())
-        return 'file';
-    return 'other';
-}
 const GLOB_MAGIC_RE = /[*?[\]{}!]/u;
 const DEFAULT_MAX_HIDDEN_DEPTH = 10;
 const GLOB_BATCH_CONCURRENCY = 64;

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,11 +1,11 @@
 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, 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 { needsStatsForSort, withOptionalStoppedReason } from './common.js';
-import { globEntries, resolveEntryType } from './glob-engine.js';
+import { isEntryAccessibleByType, needsStatsForSort, resolveEntryType, resolveStopReason, withOptionalStoppedReason, } from './common.js';
+import { globEntries } from './glob-engine.js';
 function normalizePattern(pattern) {
     if (!pattern || pattern.length === 0)
         return undefined;
@@ -40,18 +40,11 @@ function resolveMaxDepth(normalized) {
     }
     return normalized.maxDepth;
 }
-function getStopReason(signal, acceptedCount, maxEntries) {
-    if (signal.aborted)
-        return 'aborted';
-    if (acceptedCount >= maxEntries)
-        return 'maxEntries';
-    return undefined;
-}
 async function* readDirectoryEntries(basePath, normalized, needsStats, signal) {
     const dirents = await withAbort(fsp.readdir(basePath, { withFileTypes: true }), signal);
     const entries = [];
     for (const dirent of dirents) {
-        if (!normalized.includeHidden && dirent.name.startsWith('.')) {
+        if (!normalized.includeHidden && isHidden(dirent.name)) {
             continue;
         }
         entries.push({ dirent, entryPath: path.join(basePath, dirent.name) });
@@ -149,32 +142,6 @@ function trackSymlink(entryType, includeSymlinkTargets, counters) {
         counters.symlinksNotFollowed += 1;
     }
 }
-async function isEntryAccessible(entryPath, entryType, basePathDirectories, signal, counters) {
-    if (entryType !== 'symlink') {
-        const normalized = normalizePath(entryPath);
-        if (!isPathWithinDirectories(normalized, basePathDirectories)) {
-            counters.skippedInaccessible += 1;
-            return false;
-        }
-        if (isSensitivePath(entryPath, normalized)) {
-            counters.skippedInaccessible += 1;
-            return false;
-        }
-        return true;
-    }
-    try {
-        const validated = await validateExistingPathDetailed(entryPath, signal);
-        if (isSensitivePath(validated.requestedPath, validated.resolvedPath)) {
-            counters.skippedInaccessible += 1;
-            return false;
-        }
-        return true;
-    }
-    catch {
-        counters.skippedInaccessible += 1;
-        return false;
-    }
-}
 function appendEntry(entry, entryType, symlinkTarget, ctx) {
     updateTotals(entryType, ctx.totals);
     ctx.entries.push(buildDirectoryEntry(ctx.basePath, entry, entryType, ctx.needsStats, symlinkTarget));
@@ -214,6 +181,12 @@ async function collectEntries(basePath, normalized, signal, needsStats, maxDepth
     const totals = { files: 0, directories: 0 };
     const counters = { skippedInaccessible: 0, symlinksNotFollowed: 0 };
     const basePathDirectories = [basePath];
+    const accessDeps = {
+        normalizePath,
+        isPathWithinDirectories,
+        isSensitivePath,
+        validateSymlinkPath: validateExistingPathDetailed,
+    };
     let truncated = false;
     let stoppedReason;
     const pending = [];
@@ -232,7 +205,13 @@ async function collectEntries(basePath, normalized, signal, needsStats, maxDepth
         entries,
     };
     for await (const entry of stream) {
-        const stopReason = getStopReason(signal, acceptedCount, normalized.maxEntries);
+        const stopReason = resolveStopReason({
+            signal,
+            current: acceptedCount,
+            max: normalized.maxEntries,
+            abortedReason: 'aborted',
+            maxReason: 'maxEntries',
+        });
         if (stopReason) {
             truncated = true;
             stoppedReason = stopReason;
@@ -240,8 +219,9 @@ async function collectEntries(basePath, normalized, signal, needsStats, maxDepth
         }
         const entryType = resolveEntryType(entry.dirent);
         trackSymlink(entryType, normalized.includeSymlinkTargets, counters);
-        const accessible = await isEntryAccessible(entry.path, entryType, basePathDirectories, signal, counters);
+        const accessible = await isEntryAccessibleByType(entry.path, entryType, basePathDirectories, signal, accessDeps);
         if (!accessible) {
+            counters.skippedInaccessible += 1;
             continue;
         }
         acceptedCount += 1;
@@ -264,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/read-multiple-files.js

@@ -2,6 +2,7 @@ import * as fsp from 'node:fs/promises';
 import { DEFAULT_READ_MANY_MAX_TOTAL_SIZE, MAX_TEXT_FILE_SIZE, PARALLEL_CONCURRENCY, } from '../constants.js';
 import { processInParallel, readFile, readFileWithStats, withAbort, } from '../fs-helpers.js';
 import { validateExistingPath } from '../path-validation.js';
+import { applyIndexedErrors, applyIndexedValues } from './common.js';
 const UNKNOWN_PATH = '(unknown)';
 function estimateReadSize(stats, maxSize) {
     // `readFile`/`readFileWithStats` are always invoked with a `maxSize` cap, so the
@@ -173,11 +174,6 @@ function buildOutput(filePaths) {
     }
     return output;
 }
-function applyResults(output, results) {
-    for (const result of results) {
-        output[result.index] = result.value;
-    }
-}
 function resolveErrorOriginalIndex(failureIndex, filesToProcess, totalInputFiles) {
     // processInParallel implementations vary: some return error indices relative to
     // the submitted batch (filesToProcess), others may forward the task/index.
@@ -192,18 +188,6 @@ function resolveErrorOriginalIndex(failureIndex, filesToProcess, totalInputFiles
     }
     return undefined;
 }
-function applyErrors(output, errors, filesToProcess, filePaths) {
-    for (const failure of errors) {
-        const originalIndex = resolveErrorOriginalIndex(failure.index, filesToProcess, filePaths.length);
-        if (originalIndex === undefined)
-            continue;
-        const filePath = filePaths[originalIndex] ?? UNKNOWN_PATH;
-        output[originalIndex] = {
-            path: filePath,
-            error: failure.error.message,
-        };
-    }
-}
 function buildFilesToProcess(filePaths, validated, skippedBudget) {
     const filesToProcess = [];
     for (let index = 0; index < filePaths.length; index += 1) {
@@ -253,8 +237,16 @@ export async function readMultipleFiles(filePaths, options = {}) {
     const { skippedBudget, validated } = await collectFileBudget(filePaths, normalized.maxTotalSize, normalized.maxSize, signal);
     const filesToProcess = buildFilesToProcess(filePaths, validated, skippedBudget);
     const { results, errors } = await readFilesInParallel(filesToProcess, normalized, signal, options.onReadComplete);
-    applyResults(output, results);
-    applyErrors(output, errors, filesToProcess, filePaths);
+    applyIndexedValues(output, results);
+    applyIndexedErrors({
+        output,
+        errors,
+        resolveIndex: (failureIndex) => resolveErrorOriginalIndex(failureIndex, filesToProcess, filePaths.length),
+        buildValue: (resolvedIndex, error) => ({
+            path: filePaths[resolvedIndex] ?? UNKNOWN_PATH,
+            error: error.message,
+        }),
+    });
     applySkippedBudget(output, skippedBudget, filePaths, normalized.maxTotalSize);
     return output;
 }

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';