test(filesystem): bring index.ts from 0% to 98.5% coverage (per #4474 server-by-server plan)

[Parker-Fawcett]

Description

Adds src/filesystem/__tests__/index.test.ts (774 lines, 48 tests), covering the previously untested src/filesystem/index.ts — the MCP tool-registration layer. Contributes the filesystem chunk of #4474 ("Write the missing tests, server by server — each server can be its own PR") and supplies data for its first task ("Audit current coverage per server").

No production code is modified. The suite captures registerTool(name, config, handler) calls through a mocked McpServer, so the real wiring is asserted directly and handlers are invoked without exporting any test-only helpers or changing module structure.

Server Details

• Server: filesystem
• Changes to: none (tests only)

Motivation and Context

#4474 asks for a ≥90% per-file coverage gate across servers. The audit baseline shows every TS server's index.ts bootstrap/registration file sits at or near 0%, and server-filesystem had the largest such gap (~750 lines covering all 14 tools). This PR closes that gap for the repo's most-deployed reference server.

Coverage audit baseline (current main, for the #4474 tracking comment):

Server	Overall	Notable gap
everything	57.9%	server/, transports/
filesystem	46.1%	index.ts 0% ← this PR
memory	81.8%	closest to gate
sequentialthinking	54.7%	index.ts 0%

What's covered

• Registration wiring: all 14 tools registered exactly once with non-empty descriptions; annotation spot-checks (readOnlyHint/destructiveHint/idempotentHint) matching each tool's semantics.
• Handler behavior: read_text_file full/head/tail (+head+tail conflict), read_media_file image/audio/resource branches + base64 stream + stream-error propagation, read_multiple_files success + Error/non-Error failure embedding, write_file incl. wx-flag call shape, edit_file apply vs dry-run, create_directory, list_directory, list_directory_with_sizes both sort modes + stat-failure fallback + summary, directory_tree recursion + glob/plain excludePatterns, move_file, search_files match/exclude/no-match, get_file_info formatting.
• Roots protocol integration: notification-handler refresh, oninitialized capability branches (roots supported / unsupported / empty response / listRoots failure with Error and non-Error rejections), invalid-root filtering via realpath+stat validation.
• Startup: argv parsing under a fresh module evaluation (vi.resetModules()), macOS-style symlink resolution to dual original/resolved entries, inaccessible-directory skipping, the all-inaccessible exit guard, and the fatal connect-failure path.

How Has This Been Tested?

• npm run build stays clean; full workspace untouched outside the new test file.
• Filesystem suite: 206/206 passing (158 pre-existing + 48 new).
• Coverage of src/filesystem/index.ts: lines 0% → 98.54%, statements → 98.51%, functions → 100%, branches → 94.28%, clearing Bring all servers to the 90% per-file coverage gate; reintroduce the rule to AGENTS.md #4474's 90/90/90/90 gate. Server overall: 46.1% → 90.4%.
• Remaining uncovered lines (58, 77, 761) are defensive arms of warning/error logs already partially exercised; documented here rather than suppressed.

Breaking Changes

None — test-only change.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Protocol Documentation
• My changes follows MCP security best practices
• I have updated the server's README accordingly (N/A)
• I have tested this with an LLM client (N/A — no runtime behavior change; handlers verified through direct invocation over mocked transports)
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have documented all environment variables and configuration options (N/A)

Additional context

Design notes for review:

• fs/promises is mocked wholesale following the existing lib.test.ts pattern; lib.ts/path-utils.ts are intentionally not mocked so handler tests exercise real validation logic against the mock boundary.
• roots-utils.ts imports fs.promises (from 'fs'), so the 'fs' partial mock shares the same promises stub — keeping roots flows deterministic without mocking roots-utils itself.
• The startup suite re-evaluates the module with seeded argv because the real one runs at import time; it is ordered last since vi.resetModules() duplicates captured registrations.
• Happy to follow up with sibling PRs for sequentialthinking (index.ts 0%) and memory (81.8% → gate) using the same approach if this shape works for reviewers.