index.test.ts

import { describe, it, expect, beforeAll, afterAll, vi } from "vitest";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
import fs from "fs/promises";
import path from "path";
import os from "os";
import { pathToFileURL } from "url";
import { createHash } from "crypto";
import { setupServer, parseRootUri, getValidRootDirectories, updateAllowedDirectoriesFromRoots } from "./index.js";
import { setAllowedDirectories, getAllowedDirectories, getAllowedRoots, setAllowedRoots, hasErrorCode } from "./lib.js";

// Helper type for MCP tool call result content items
interface ContentItem { type: string; text?: string; data?: string; mimeType?: string; }

// Helper type for directory tree entries
interface TreeEntry { name: string; type: string; children?: TreeEntry[]; }

function sha256(content: string): string {
  return createHash("sha256").update(content).digest("hex");
}

async function createOutsideDirectory(prefix = "fs-mcp-outside-"): Promise<string> {
  const rawDir = await fs.mkdtemp(path.join(os.tmpdir(), prefix));
  return fs.realpath(rawDir);
}

async function createDirectorySymlink(target: string, linkPath: string): Promise<void> {
  await fs.symlink(target, linkPath, process.platform === "win32" ? "junction" : "dir");
}

// In-process integration tests using InMemoryTransport for v8 coverage
describe("index.ts integration", () => {
  let client: Client;
  let testDir: string;

  beforeAll(async () => {
    const rawDir = await fs.mkdtemp(path.join(os.tmpdir(), "fs-mcp-integration-"));
    testDir = await fs.realpath(rawDir);

    // Create test fixtures
    await fs.writeFile(path.join(testDir, "hello.txt"), "line1\nline2\nline3\nline4\nline5\n");
    await fs.writeFile(path.join(testDir, "data.json"), '{"key": "value"}');
    await fs.mkdir(path.join(testDir, "subdir"), { recursive: true });
    await fs.writeFile(path.join(testDir, "subdir", "nested.txt"), "nested content");

    // Set allowed directories BEFORE creating the server
    setAllowedDirectories([testDir, rawDir]);

    const server = setupServer();
    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
    await server.connect(serverTransport);

    client = new Client({ name: "test-client", version: "1.0.0" });
    await client.connect(clientTransport);
  }, 15000);

  afterAll(async () => {
    try { await client?.close(); } catch { /* ignore cleanup */ }
    setAllowedDirectories([]);
    await fs.rm(testDir, { recursive: true, force: true });
  });

  // --- Tool Listing ---
  it("should list all registered tools", async () => {
    const tools = await client.listTools();
    const toolNames = tools.tools.map((t: { name: string }) => t.name);
    expect(toolNames).toContain("read_file");
    expect(toolNames).toContain("read_text_file");
    expect(toolNames).toContain("read_media_file");
    expect(toolNames).toContain("read_multiple_files");
    expect(toolNames).toContain("write_file");
    expect(toolNames).toContain("edit_file");
    expect(toolNames).toContain("create_directory");
    expect(toolNames).toContain("list_directory");
    expect(toolNames).toContain("list_directory_with_sizes");
    expect(toolNames).toContain("directory_tree");
    expect(toolNames).toContain("rename_file");
    expect(toolNames).toContain("search_files");
    expect(toolNames).toContain("get_file_info");
    expect(toolNames).toContain("list_allowed_directories");
  });

  // --- read_file ---
  describe("read_file", () => {
    it("should read full file", async () => {
      const result = await client.callTool({ name: "read_file", arguments: { path: path.join(testDir, "hello.txt") } });
      const text = (result.content as ContentItem[])[0].text;
      expect(text).toContain("line1");
      expect(text).toContain("line5");
    });

    it("should read line range", async () => {
      const result = await client.callTool({ name: "read_file", arguments: { path: path.join(testDir, "hello.txt"), start_line: 2, end_line: 3 } });
      const text = (result.content as ContentItem[])[0].text;
      expect(text).toContain("line2");
      expect(text).toContain("line3");
      expect(text).not.toContain("line1");
    });

    it("should support head parameter", async () => {
      const result = await client.callTool({ name: "read_file", arguments: { path: path.join(testDir, "hello.txt"), head: 2 } });
      const text = (result.content as ContentItem[])[0].text!;
      const lines = text.split("\n").filter(Boolean);
      expect(lines.length).toBe(2);
      expect(lines[0]).toBe("line1");
    });

    it("should support tail parameter", async () => {
      const result = await client.callTool({ name: "read_file", arguments: { path: path.join(testDir, "hello.txt"), tail: 2 } });
      const text = (result.content as ContentItem[])[0].text;
      expect(text).toContain("line5");
    });

    it("should reject head + tail together", async () => {
      const result = await client.callTool({ name: "read_file", arguments: { path: path.join(testDir, "hello.txt"), head: 2, tail: 2 } });
      expect(result.isError).toBe(true);
    });

    it("should reject head + start_line together", async () => {
      const result = await client.callTool({ name: "read_file", arguments: { path: path.join(testDir, "hello.txt"), head: 2, start_line: 1 } });
      expect(result.isError).toBe(true);
    });

    it("should reject start_line > end_line", async () => {
      const result = await client.callTool({ name: "read_file", arguments: { path: path.join(testDir, "hello.txt"), start_line: 5, end_line: 2 } });
      expect(result.isError).toBe(true);
    });

    it("should reject non-positive and fractional line controls", async () => {
      const filePath = path.join(testDir, "hello.txt");
      const invalidCalls = [
        { start_line: 0 },
        { end_line: -1 },
        { head: 0 },
        { tail: -2 },
        { start_line: 1.5 },
        { end_line: 2.25 },
        { head: 1.5 },
        { tail: 2.25 },
      ];

      for (const args of invalidCalls) {
        const result = await client.callTool({ name: "read_file", arguments: { path: filePath, ...args } });
        expect(result.isError).toBe(true);
      }
    });

    it("should error for path outside allowed directories", async () => {
      const result = await client.callTool({ name: "read_file", arguments: { path: "/etc/passwd" } });
      expect(result.isError).toBe(true);
    });

    it("should support encoding parameter", async () => {
      const result = await client.callTool({ name: "read_file", arguments: { path: path.join(testDir, "hello.txt"), encoding: "ascii" } });
      const text = (result.content as ContentItem[])[0].text;
      expect(text).toContain("line1");
    });

    it("should reject invalid encoding", async () => {
      const result = await client.callTool({ name: "read_file", arguments: { path: path.join(testDir, "hello.txt"), encoding: "cp1252" } });
      expect(result.isError).toBe(true);
    });

    it("should return numbered lines and structured line metadata when requested", async () => {
      const result = await client.callTool({
        name: "read_file",
        arguments: {
          path: path.join(testDir, "hello.txt"),
          start_line: 2,
          end_line: 3,
          show_line_numbers: true,
          output_format: "both",
        },
      });

      expect(result.isError).toBeFalsy();
      const text = (result.content as ContentItem[])[0].text!;
      expect(text).toContain("2 | line2");
      expect(text).toContain("3 | line3");
      expect(text).not.toContain("line1");

      const structured = result.structuredContent as { lines?: Array<{ lineNumber: number; text: string }>; startLine?: number; endLine?: number };
      expect(structured.startLine).toBe(2);
      expect(structured.endLine).toBe(3);
      expect(structured.lines).toEqual([
        { lineNumber: 2, text: "line2" },
        { lineNumber: 3, text: "line3" },
      ]);
    });

    it("should read around a line with before/after context", async () => {
      const result = await client.callTool({
        name: "read_file",
        arguments: {
          path: path.join(testDir, "hello.txt"),
          mode: "around",
          line: 3,
          before: 1,
          after: 1,
          show_line_numbers: true,
        },
      });

      expect(result.isError).toBeFalsy();
      const text = (result.content as ContentItem[])[0].text!;
      expect(text).toContain("2 | line2");
      expect(text).toContain("3 | line3");
      expect(text).toContain("4 | line4");
      expect(text).not.toContain("1 | line1");
    });

    it("should read matching lines with context", async () => {
      const result = await client.callTool({
        name: "read_file",
        arguments: {
          path: path.join(testDir, "hello.txt"),
          mode: "matches",
          pattern: "line[24]",
          search_mode: "regex",
          before: 0,
          after: 0,
          show_line_numbers: true,
        },
      });

      expect(result.isError).toBeFalsy();
      const text = (result.content as ContentItem[])[0].text!;
      expect(text).toContain("2 | line2");
      expect(text).toContain("4 | line4");
      const structured = result.structuredContent as { matches?: Array<{ lineNumber: number; text: string }> };
      expect(structured.matches?.map((match) => match.lineNumber)).toEqual([2, 4]);
    });

    it("should support full reads with line numbers and max_lines truncation", async () => {
      const result = await client.callTool({
        name: "read_file",
        arguments: { path: path.join(testDir, "hello.txt"), show_line_numbers: true, max_lines: 2 },
      });

      expect(result.isError).toBeFalsy();
      const text = (result.content as ContentItem[])[0].text!;
      expect(text).toBe("1 | line1\n2 | line2");
      expect(result.result).toMatchObject({ warningCode: "CONTENT_TRUNCATED" });
    });

    it("should truncate full reads by max_bytes", async () => {
      const result = await client.callTool({
        name: "read_file",
        arguments: { path: path.join(testDir, "hello.txt"), max_bytes: 5 },
      });

      expect(result.isError).toBeFalsy();
      expect((result.content as ContentItem[])[0].text).toBe("line1");
      expect(result.result).toMatchObject({ warningCode: "CONTENT_TRUNCATED" });
    });

    it("should validate explicit read modes", async () => {
      const headWithoutCount = await client.callTool({
        name: "read_file",
        arguments: { path: path.join(testDir, "hello.txt"), mode: "head" },
      });
      expect(headWithoutCount.isError).toBe(true);

      const aroundWithoutLine = await client.callTool({
        name: "read_file",
        arguments: { path: path.join(testDir, "hello.txt"), mode: "around" },
      });
      expect(aroundWithoutLine.isError).toBe(true);

      const matchesWithoutPattern = await client.callTool({
        name: "read_file",
        arguments: { path: path.join(testDir, "hello.txt"), mode: "matches" },
      });
      expect(matchesWithoutPattern.isError).toBe(true);
    });

    it("should truncate read_file matches and include context metadata", async () => {
      const result = await client.callTool({
        name: "read_file",
        arguments: {
          path: path.join(testDir, "hello.txt"),
          mode: "matches",
          pattern: "line",
          before: 1,
          after: 1,
          max_matches: 1,
        },
      });

      expect(result.isError).toBeFalsy();
      expect(result.result).toMatchObject({ warningCode: "RESULTS_TRUNCATED" });
      const structured = result.structuredContent as { matches?: Array<{ lineNumber: number; before?: unknown[]; after?: unknown[] }> };
      expect(structured.matches).toHaveLength(1);
      expect(structured.matches?.[0].lineNumber).toBe(1);
      expect(structured.matches?.[0].after).toHaveLength(1);
    });
  });

  // --- read_text_file ---
  describe("read_text_file", () => {
    it("should read full file", async () => {
      const result = await client.callTool({ name: "read_text_file", arguments: { path: path.join(testDir, "hello.txt") } });
      expect((result.content as ContentItem[])[0].text).toContain("line1");
    });

    it("should support head", async () => {
      const result = await client.callTool({ name: "read_text_file", arguments: { path: path.join(testDir, "hello.txt"), head: 1 } });
      expect((result.content as ContentItem[])[0].text).toBe("line1");
    });

    it("should support tail", async () => {
      const result = await client.callTool({ name: "read_text_file", arguments: { path: path.join(testDir, "hello.txt"), tail: 2 } });
      const text = (result.content as ContentItem[])[0].text;
      expect(text).toContain("line5");
    });

    it("should reject head + tail together", async () => {
      const result = await client.callTool({ name: "read_text_file", arguments: { path: path.join(testDir, "hello.txt"), head: 1, tail: 1 } });
      expect(result.isError).toBe(true);
    });

    it("should reject negative and fractional head/tail values", async () => {
      const negative = await client.callTool({ name: "read_text_file", arguments: { path: path.join(testDir, "hello.txt"), head: -1 } });
      expect(negative.isError).toBe(true);

      const fractional = await client.callTool({ name: "read_text_file", arguments: { path: path.join(testDir, "hello.txt"), tail: 1.5 } });
      expect(fractional.isError).toBe(true);
    });
  });

  // --- read_media_file ---
  describe("read_media_file", () => {
    it("should read file as base64 with MIME type", async () => {
      const pngPath = path.join(testDir, "media-test.png");
      await fs.writeFile(pngPath, Buffer.from("fake png content for base64 testing"));
      const result = await client.callTool({ name: "read_media_file", arguments: { path: pngPath } });
      expect(result.isError).toBeFalsy();
      const content = (result.content as ContentItem[])[0];
      expect(content.mimeType).toBe("image/png");
      expect(content.data).toBeTruthy();
    });

    it("should not emit SVG as MCP image content", async () => {
      const svgPath = path.join(testDir, "active-content.svg");
      await fs.writeFile(svgPath, '<svg xmlns="http://www.w3.org/2000/svg"><script>alert(1)</script></svg>');
      const result = await client.callTool({ name: "read_media_file", arguments: { path: svgPath } });
      expect(result.isError).toBeFalsy();
      const content = (result.content as ContentItem[])[0];
      expect(content.type).toBe("text");
      expect(content.text).toContain("base64 data omitted");
      expect(content.data).toBeUndefined();
    });

    it("should read audio files as MCP audio content", async () => {
      const audioPath = path.join(testDir, "audio-test.mp3");
      await fs.writeFile(audioPath, Buffer.from("fake mp3 content for base64 testing"));
      const result = await client.callTool({ name: "read_media_file", arguments: { path: audioPath } });
      expect(result.isError).toBeFalsy();
      const content = (result.content as ContentItem[])[0];
      expect(content.type).toBe("audio");
      expect(content.mimeType).toBe("audio/mpeg");
      expect(content.data).toBeTruthy();
    });
  });

  // --- read_multiple_files ---
  describe("read_multiple_files", () => {
    it("should read multiple files", async () => {
      const result = await client.callTool({ name: "read_multiple_files", arguments: { paths: [path.join(testDir, "hello.txt"), path.join(testDir, "data.json")] } });
      const text = (result.content as ContentItem[])[0].text;
      expect(text).toContain("line1");
      expect(text).toContain('"key"');
    });

    it("should include error for non-existent file inline", async () => {
      const result = await client.callTool({ name: "read_multiple_files", arguments: { paths: [path.join(testDir, "hello.txt"), path.join(testDir, "nonexistent.txt")] } });
      const text = (result.content as ContentItem[])[0].text;
      expect(text).toContain("line1");
      expect(text).toContain("Error");
    });

    it("should include structured per-file success and error entries", async () => {
      const missingPath = path.join(testDir, "missing-multiple.txt");
      const result = await client.callTool({
        name: "read_multiple_files",
        arguments: { paths: [path.join(testDir, "hello.txt"), missingPath], output_format: "both" },
      });

      expect(result.isError).toBeFalsy();
      const structured = result.structuredContent as { files?: Array<{ path: string; success: boolean; content?: string; errorCode?: string }> };
      expect(structured.files).toHaveLength(2);
      expect(structured.files?.[0]).toMatchObject({ path: path.join(testDir, "hello.txt"), success: true });
      expect(structured.files?.[0].content).toContain("line1");
      expect(structured.files?.[1]).toMatchObject({ path: missingPath, success: false, errorCode: "PATH_NOT_FOUND" });
    });
  });

  // --- write_file ---
  describe("write_file", () => {
    it("should create a new file", async () => {
      const filePath = path.join(testDir, "new-write.txt");
      const result = await client.callTool({ name: "write_file", arguments: { path: filePath, content: "new content" } });
      expect(result.isError).toBeFalsy();
      const content = await fs.readFile(filePath, "utf-8");
      expect(content).toBe("new content");
    });

    it("should fail on existing file without overwrite", async () => {
      const filePath = path.join(testDir, "new-write.txt");
      const result = await client.callTool({ name: "write_file", arguments: { path: filePath, content: "overwrite attempt" } });
      expect(result.isError).toBe(true);
      expect((result.content as ContentItem[])[0].text).toContain("already exists");
    });

    it("should overwrite with overwrite: true", async () => {
      const filePath = path.join(testDir, "new-write.txt");
      const result = await client.callTool({ name: "write_file", arguments: { path: filePath, content: "overwritten", overwrite: true } });
      expect(result.isError).toBeFalsy();
      expect(await fs.readFile(filePath, "utf-8")).toBe("overwritten");
    });

    it("should append with append: true", async () => {
      const filePath = path.join(testDir, "new-write.txt");
      await client.callTool({ name: "write_file", arguments: { path: filePath, content: " more", append: true } });
      expect(await fs.readFile(filePath, "utf-8")).toBe("overwritten more");
    });

    it("should create parent directories with create_parents", async () => {
      const filePath = path.join(testDir, "deep", "nested", "dir", "file.txt");
      const result = await client.callTool({ name: "write_file", arguments: { path: filePath, content: "deep", create_parents: true } });
      expect(result.isError).toBeFalsy();
      expect(await fs.readFile(filePath, "utf-8")).toBe("deep");
    });

    it("should support dry-run writes with diff output", async () => {
      const filePath = path.join(testDir, "write-dry-run.txt");
      await fs.writeFile(filePath, "before\n");

      const result = await client.callTool({
        name: "write_file",
        arguments: { path: filePath, content: "after\n", overwrite: true, dryRun: true, return_diff: true },
      });

      expect(result.isError).toBeFalsy();
      expect(await fs.readFile(filePath, "utf-8")).toBe("before\n");
      const text = (result.content as ContentItem[])[0].text!;
      expect(text).toContain("-before");
      expect(text).toContain("+after");
    });

    it("should reject writes when expected_hash does not match current content", async () => {
      const filePath = path.join(testDir, "write-hash-guard.txt");
      await fs.writeFile(filePath, "current");

      const result = await client.callTool({
        name: "write_file",
        arguments: { path: filePath, content: "changed", overwrite: true, expected_hash: sha256("different") },
      });

      expect(result.isError).toBe(true);
      expect(await fs.readFile(filePath, "utf-8")).toBe("current");
    });

    it("should support expected_modified guards, backup creation, and diff output", async () => {
      const filePath = path.join(testDir, "write-guarded-backup.txt");
      await fs.writeFile(filePath, "before");
      const modified = (await fs.stat(filePath)).mtime.toISOString();

      const result = await client.callTool({
        name: "write_file",
        arguments: {
          path: filePath,
          content: "after",
          overwrite: true,
          expected_hash: sha256("before"),
          expected_modified: modified,
          create_backup: true,
          return_diff: true,
          output_format: "both",
        },
      });

      expect(result.isError).toBeFalsy();
      expect(await fs.readFile(filePath, "utf-8")).toBe("after");
      const structured = result.structuredContent as { backupPath?: string; diff?: string };
      expect(structured.backupPath).toBeTruthy();
      expect(await fs.readFile(structured.backupPath!, "utf-8")).toBe("before");
      expect(structured.diff).toContain("-before");
      expect(structured.diff).toContain("+after");
    });

    it("should reject expected state checks for files that do not exist", async () => {
      const filePath = path.join(testDir, "write-missing-expected.txt");
      const result = await client.callTool({
        name: "write_file",
        arguments: { path: filePath, content: "new", expected_hash: sha256("") },
      });

      expect(result.isError).toBe(true);
      expect(result.result).toMatchObject({ errorCode: "PATH_NOT_FOUND" });
    });
  });

  // --- edit_file ---
  describe("edit_file", () => {
    it("should apply an edit and return diff", async () => {
      const filePath = path.join(testDir, "edit-target.txt");
      await fs.writeFile(filePath, "original line\n");
      const result = await client.callTool({ name: "edit_file", arguments: { path: filePath, edits: [{ oldText: "original line", newText: "modified line" }] } });
      expect(result.isError).toBeFalsy();
      const text = (result.content as ContentItem[])[0].text;
      expect(text).toContain("original line");
      expect(text).toContain("modified line");
      expect(await fs.readFile(filePath, "utf-8")).toContain("modified line");
    });

    it("should support dryRun", async () => {
      const filePath = path.join(testDir, "edit-target.txt");
      await fs.writeFile(filePath, "keep me\n");
      const result = await client.callTool({ name: "edit_file", arguments: { path: filePath, edits: [{ oldText: "keep me", newText: "changed" }], dryRun: true } });
      expect(result.isError).toBeFalsy();
      expect(await fs.readFile(filePath, "utf-8")).toContain("keep me");
    });

    it("should support line-range replacements", async () => {
      const filePath = path.join(testDir, "edit-lines.txt");
      await fs.writeFile(filePath, "one\ntwo\nthree\n");

      const result = await client.callTool({
        name: "edit_file",
        arguments: { path: filePath, edits: [{ start_line: 2, end_line: 2, newText: "TWO" }] },
      });

      expect(result.isError).toBeFalsy();
      expect(await fs.readFile(filePath, "utf-8")).toBe("one\nTWO\nthree\n");
    });

    it("should support line insertion", async () => {
      const filePath = path.join(testDir, "edit-insert.txt");
      await fs.writeFile(filePath, "one\nthree\n");

      const result = await client.callTool({
        name: "edit_file",
        arguments: { path: filePath, edits: [{ insert_at_line: 2, newText: "two" }] },
      });

      expect(result.isError).toBeFalsy();
      expect(await fs.readFile(filePath, "utf-8")).toBe("one\ntwo\nthree\n");
    });

    it("should reject edits when expected_hash does not match current content", async () => {
      const filePath = path.join(testDir, "edit-hash-guard.txt");
      await fs.writeFile(filePath, "current");

      const result = await client.callTool({
        name: "edit_file",
        arguments: {
          path: filePath,
          edits: [{ oldText: "current", newText: "changed" }],
          expected_hash: sha256("different"),
        },
      });

      expect(result.isError).toBe(true);
      expect(await fs.readFile(filePath, "utf-8")).toBe("current");
    });
  });

  // --- create_directory ---
  describe("create_directory", () => {
    it("should create a new directory", async () => {
      const dirPath = path.join(testDir, "new-dir");
      const result = await client.callTool({ name: "create_directory", arguments: { path: dirPath } });
      expect(result.isError).toBeFalsy();
      const stat = await fs.stat(dirPath);
      expect(stat.isDirectory()).toBe(true);
    });

    it("should succeed silently if directory already exists", async () => {
      const dirPath = path.join(testDir, "new-dir");
      const result = await client.callTool({ name: "create_directory", arguments: { path: dirPath } });
      expect(result.isError).toBeFalsy();
    });
  });

  // --- list_directory ---
  describe("list_directory", () => {
    it("should list directory contents", async () => {
      const result = await client.callTool({ name: "list_directory", arguments: { path: testDir } });
      const text = (result.content as ContentItem[])[0].text;
      expect(text).toContain("hello.txt");
      expect(text).toContain("[FILE]");
      expect(text).toContain("[DIR]");
    });

    it("should list recursively", async () => {
      const result = await client.callTool({ name: "list_directory", arguments: { path: testDir, recursive: true } });
      const text = (result.content as ContentItem[])[0].text;
      expect(text).toContain("nested.txt");
    });

    it("should include metadata when requested", async () => {
      const result = await client.callTool({ name: "list_directory", arguments: { path: testDir, include_metadata: true } });
      const text = (result.content as ContentItem[])[0].text;
      expect(text).toContain("Size:");
      expect(text).toContain("Total:");
    });

    it("should support sorting", async () => {
      const result = await client.callTool({ name: "list_directory", arguments: { path: testDir, sortBy: "name", order: "desc" } });
      expect(result.isError).toBeFalsy();
    });

    it("should sort by size", async () => {
      const result = await client.callTool({ name: "list_directory", arguments: { path: testDir, sortBy: "size" } });
      expect(result.isError).toBeFalsy();
    });

    it("should sort by modified date", async () => {
      const result = await client.callTool({ name: "list_directory", arguments: { path: testDir, sortBy: "modified" } });
      expect(result.isError).toBeFalsy();
    });

    it("should include metadata in recursive listing", async () => {
      const result = await client.callTool({ name: "list_directory", arguments: { path: testDir, recursive: true, include_metadata: true } });
      const text = (result.content as ContentItem[])[0].text;
      expect(text).toContain("Size:");
    });

    it("should provide structured entries and respect hidden/depth options", async () => {
      const hiddenFile = path.join(testDir, ".hidden-list-entry");
      await fs.writeFile(hiddenFile, "hidden");

      const result = await client.callTool({
        name: "list_directory",
        arguments: { path: testDir, recursive: true, include_metadata: true, include_hidden: false, maxDepth: 1, output_format: "both" },
      });

      expect(result.isError).toBeFalsy();
      const text = (result.content as ContentItem[])[0].text!;
      expect(text).not.toContain(".hidden-list-entry");
      expect(text).not.toContain("nested.txt");
      const structured = result.structuredContent as { entries?: Array<{ name: string; type: string; size?: number; modified?: string; errorCode?: string; depth: number }> };
      expect(structured.entries?.some((entry) => entry.name === "hello.txt" && entry.type === "file")).toBe(true);
      expect(structured.entries?.some((entry) => entry.name === ".hidden-list-entry")).toBe(false);
      expect(structured.entries?.every((entry) => entry.depth <= 1)).toBe(true);
    });

    it("should support structured-only rendering and field filtering", async () => {
      const result = await client.callTool({
        name: "list_directory",
        arguments: { path: testDir, include_metadata: true, fields: ["size"], output_format: "structured" },
      });

      expect(result.isError).toBeFalsy();
      const text = (result.content as ContentItem[])[0].text!;
      expect(() => JSON.parse(text)).not.toThrow();
      const structured = result.structuredContent as { entries?: Array<Record<string, unknown>> };
      const hello = structured.entries?.find((entry) => entry.name === "hello.txt");
      expect(hello?.size).toBeTypeOf("number");
      expect(hello?.modified).toBeUndefined();
    });
  });

  // --- list_directory_with_sizes ---
  describe("list_directory_with_sizes", () => {
    it("should list with sizes and dates", async () => {
      const result = await client.callTool({ name: "list_directory_with_sizes", arguments: { path: testDir } });
      const text = (result.content as ContentItem[])[0].text;
      expect(text).toContain("hello.txt");
      expect(text).toContain("Total:");
    });

    it("should support sort by size", async () => {
      const result = await client.callTool({ name: "list_directory_with_sizes", arguments: { path: testDir, sortBy: "size" } });
      expect(result.isError).toBeFalsy();
    });

    it("should not follow symlinks outside allowed roots for metadata", async () => {
      const rawDir = await fs.mkdtemp(path.join(os.tmpdir(), "fs-mcp-symlink-metadata-"));
      const realDir = await fs.realpath(rawDir);
      const outsideDir = await createOutsideDirectory();
      const previousRoots = getAllowedDirectories();
      try {
        await fs.writeFile(path.join(outsideDir, "secret.txt"), "outside");
        try {
          await createDirectorySymlink(outsideDir, path.join(rawDir, "outside-link"));
        } catch (error: unknown) {
          if (hasErrorCode(error) && (error.code === "EPERM" || error.code === "EACCES")) return;
          throw error;
        }
        setAllowedDirectories([rawDir, realDir]);

        const listing = await client.callTool({ name: "list_directory", arguments: { path: rawDir, include_metadata: true } });
        const listingText = (listing.content as ContentItem[])[0].text!;
        expect(listingText).toContain("outside-link");
        expect(listingText).toContain("ACCESS_DENIED");
        expect(listingText).not.toMatch(/outside-link \(Size:/);

        const sizes = await client.callTool({ name: "list_directory_with_sizes", arguments: { path: rawDir } });
        const sizesText = (sizes.content as ContentItem[])[0].text!;
        expect(sizesText).toContain("outside-link");
        expect(sizesText).toContain("ACCESS_DENIED");
      } finally {
        setAllowedDirectories(previousRoots);
        await fs.rm(rawDir, { recursive: true, force: true });
        await fs.rm(outsideDir, { recursive: true, force: true });
      }
    });
  });

  // --- directory_tree ---
  describe("directory_tree", () => {
    it("should return JSON tree", async () => {
      const result = await client.callTool({ name: "directory_tree", arguments: { path: testDir } });
      const text = (result.content as ContentItem[])[0].text!;
      const tree = JSON.parse(text);
      expect(Array.isArray(tree)).toBe(true);
      const names = (tree as TreeEntry[]).map((e) => e.name);
      expect(names).toContain("hello.txt");
    });

    it("should respect excludePatterns", async () => {
      const result = await client.callTool({ name: "directory_tree", arguments: { path: testDir, excludePatterns: ["subdir/**"] } });
      const text = (result.content as ContentItem[])[0].text;
      expect(text).not.toContain("nested.txt");
    });

    it("should respect maxDepth", async () => {
      const result = await client.callTool({ name: "directory_tree", arguments: { path: testDir, maxDepth: 1 } });
      const tree = JSON.parse((result.content as ContentItem[])[0].text!) as TreeEntry[];
      const subdir = tree.find((e) => e.name === "subdir");
      if (subdir) {
        expect(subdir.children?.length || 0).toBe(0);
      }
    });
  });

  // --- rename_file ---
  describe("rename_file", () => {
    it("should rename a file", async () => {
      const src = path.join(testDir, "rename-me.txt");
      const dst = path.join(testDir, "renamed.txt");
      await fs.writeFile(src, "rename content");
      const result = await client.callTool({ name: "rename_file", arguments: { source: src, destination: dst } });
      expect(result.isError).toBeFalsy();
      expect(await fs.readFile(dst, "utf-8")).toBe("rename content");
      await expect(fs.access(src)).rejects.toThrow();
    });

    it("should fail if destination exists", async () => {
      const src = path.join(testDir, "renamed.txt");
      const dst = path.join(testDir, "hello.txt");
      const result = await client.callTool({ name: "rename_file", arguments: { source: src, destination: dst } });
      expect(result.isError).toBe(true);
      expect((result.content as ContentItem[])[0].text).toContain("already exists");
    });

    it("should refuse cross-root renames so rename cannot be used as a delete workaround", async () => {
      const src = path.join(testDir, "cross-root-source.txt");
      const otherRawDir = await fs.mkdtemp(path.join(os.tmpdir(), "fs-mcp-cross-root-"));
      const otherDir = await fs.realpath(otherRawDir);
      const previousRoots = getAllowedDirectories();
      try {
        setAllowedDirectories([testDir, otherDir]);
        await fs.writeFile(src, "do not rename across roots");
        const dst = path.join(otherDir, "cross-root-dest.txt");

        const result = await client.callTool({ name: "rename_file", arguments: { source: src, destination: dst } });

        expect(result.isError).toBe(true);
        expect((result.content as ContentItem[])[0].text).toContain("Cross-root renames are refused");
        expect(await fs.readFile(src, "utf-8")).toBe("do not rename across roots");
        await expect(fs.access(dst)).rejects.toThrow();
      } finally {
        setAllowedDirectories(previousRoots);
        await fs.rm(otherDir, { recursive: true, force: true });
      }
    });

    it("should refuse EXDEV instead of falling back to copy plus delete", async () => {
      const src = path.join(testDir, "exdev-source.txt");
      const dst = path.join(testDir, "exdev-dest.txt");
      await fs.writeFile(src, "same-root cross-device refusal");
      const originalRename = fs.rename.bind(fs);
      const renameSpy = vi.spyOn(fs, "rename").mockImplementation(async (source, destination) => {
        if (source === src && destination === dst) {
          throw Object.assign(new Error("cross-device link not permitted"), { code: "EXDEV" });
        }
        return originalRename(source, destination);
      });
      try {
        const result = await client.callTool({ name: "rename_file", arguments: { source: src, destination: dst } });

        expect(result.isError).toBe(true);
        expect((result.content as ContentItem[])[0].text).toContain("does not emulate rename with copy/delete");
        expect(await fs.readFile(src, "utf-8")).toBe("same-root cross-device refusal");
        await expect(fs.access(dst)).rejects.toThrow();
      } finally {
        renameSpy.mockRestore();
      }
    });
  });

  // --- search_files ---
  describe("search_files", () => {
    it("should search by substring", async () => {
      const result = await client.callTool({ name: "search_files", arguments: { path: testDir, pattern: "hello" } });
      const text = (result.content as ContentItem[])[0].text;
      expect(text).toContain("hello.txt");
    });

    it("should search by regex", async () => {
      const result = await client.callTool({ name: "search_files", arguments: { path: testDir, pattern: "\\.txt$", search_mode: "regex" } });
      const text = (result.content as ContentItem[])[0].text;
      expect(text).toContain(".txt");
    });

    it("should search by glob", async () => {
      const result = await client.callTool({ name: "search_files", arguments: { path: testDir, pattern: "*.json", search_mode: "glob" } });
      const text = (result.content as ContentItem[])[0].text;
      expect(text).toContain("data.json");
    });

    it("should support max_results", async () => {
      const result = await client.callTool({ name: "search_files", arguments: { path: testDir, pattern: "", max_results: 1 } });
      expect(result.isError).toBeFalsy();
    });

    it("should support match_path", async () => {
      const result = await client.callTool({ name: "search_files", arguments: { path: testDir, pattern: "subdir", match_path: true } });
      const text = (result.content as ContentItem[])[0].text;
      expect(text).toContain("subdir");
    });

    it("should report error for invalid regex", async () => {
      const result = await client.callTool({ name: "search_files", arguments: { path: testDir, pattern: "[invalid", search_mode: "regex" } });
      expect(result.isError).toBe(true);
    });

    it("should search file contents with line context and structured matches", async () => {
      const result = await client.callTool({
        name: "search_files",
        arguments: {
          path: testDir,
          pattern: "line[24]",
          search_mode: "regex",
          target: "content",
          include_context: true,
          before: 0,
          after: 0,
          show_line_numbers: true,
          output_format: "both",
        },
      });

      expect(result.isError).toBeFalsy();
      const text = (result.content as ContentItem[])[0].text!;
      expect(text).toContain("hello.txt:2 | line2");
      expect(text).toContain("hello.txt:4 | line4");
      const structured = result.structuredContent as { matches?: Array<{ path: string; lineNumber: number; text: string }> };
      expect(structured.matches?.filter((match) => match.path.endsWith("hello.txt")).map((match) => match.lineNumber)).toEqual([2, 4]);
    });

    it("should reject glob mode for content-only search", async () => {
      const result = await client.callTool({
        name: "search_files",
        arguments: { path: testDir, pattern: "*.txt", search_mode: "glob", target: "content" },
      });

      expect(result.isError).toBe(true);
    });

    it("should report skipped files for content search size and binary policies", async () => {
      const smallLimit = await client.callTool({
        name: "search_files",
        arguments: { path: testDir, pattern: "line", target: "content", max_file_bytes: 1 },
      });
      expect(smallLimit.isError).toBeFalsy();
      const smallLimitStructured = smallLimit.structuredContent as { skippedFiles?: unknown[] };
      expect(smallLimitStructured.skippedFiles?.length).toBeGreaterThan(0);

      const binaryPath = path.join(testDir, "content-binary.bin");
      await fs.writeFile(binaryPath, Buffer.from("needle\x00value"));
      const includeWarning = await client.callTool({
        name: "search_files",
        arguments: { path: testDir, pattern: "needle", target: "content", binary_policy: "include_warning" },
      });
      expect(includeWarning.isError).toBeFalsy();
      const warningStructured = includeWarning.structuredContent as { matches?: Array<{ path: string }>; skippedFiles?: Array<{ errorCode?: string }> };
      expect(warningStructured.matches?.some((match) => match.path.endsWith("content-binary.bin"))).toBe(true);
      expect(warningStructured.skippedFiles?.some((file) => file.errorCode === "BINARY_CONTENT_DETECTED")).toBe(true);
    });

    it("should combine path and content matches with target all", async () => {
      const allTargetPath = path.join(testDir, "needle-name.txt");
      await fs.writeFile(allTargetPath, "needle body");
      const result = await client.callTool({
        name: "search_files",
        arguments: { path: testDir, pattern: "needle", target: "all", output_format: "both" },
      });

      expect(result.isError).toBeFalsy();
      const structured = result.structuredContent as { paths?: string[]; contentMatches?: Array<{ path: string }> };
      expect(structured.paths?.some((matchedPath) => matchedPath.endsWith("needle-name.txt"))).toBe(true);
      expect(structured.contentMatches?.some((match) => match.path.endsWith("needle-name.txt"))).toBe(true);
    });
  });

  // --- get_file_info ---
  describe("get_file_info", () => {
    it("should return file metadata", async () => {
      const result = await client.callTool({ name: "get_file_info", arguments: { path: path.join(testDir, "hello.txt") } });
      const text = (result.content as ContentItem[])[0].text;
      expect(text).toContain("isFile: true");
      expect(text).toContain("size:");
      expect(text).toContain("lineCount:");
    });

    it("should return directory metadata", async () => {
      const result = await client.callTool({ name: "get_file_info", arguments: { path: testDir } });
      const text = (result.content as ContentItem[])[0].text;
      expect(text).toContain("isDirectory: true");
    });

    it("should include mimeType for known extensions", async () => {
      const result = await client.callTool({ name: "get_file_info", arguments: { path: path.join(testDir, "data.json") } });
      const text = (result.content as ContentItem[])[0].text;
      expect(text).toContain("application/json");
    });

    it("should return structured metadata for multiple paths", async () => {
      const result = await client.callTool({
        name: "get_file_info",
        arguments: { paths: [path.join(testDir, "hello.txt"), path.join(testDir, "data.json")], output_format: "both" },
      });

      expect(result.isError).toBeFalsy();
      const structured = result.structuredContent as { files?: Array<{ path: string; success: boolean; isFile?: boolean; mimeType?: string; lineCount?: number }> };
      expect(structured.files).toHaveLength(2);
      expect(structured.files?.[0]).toMatchObject({ path: path.join(testDir, "hello.txt"), success: true, isFile: true });
      expect(structured.files?.[0].lineCount).toBeGreaterThan(0);
      expect(structured.files?.[1]).toMatchObject({ path: path.join(testDir, "data.json"), success: true, mimeType: "application/json" });
    });

    it("should include access explanation and resolved path when requested", async () => {
      const result = await client.callTool({
        name: "get_file_info",
        arguments: { path: path.join(testDir, "hello.txt"), resolve: true, explain_access: true, output_format: "both" },
      });

      expect(result.isError).toBeFalsy();
      const structured = result.structuredContent as { resolvedPath?: string; allowed?: boolean; allowedRoots?: string[] };
      expect(structured.resolvedPath).toBe(path.join(testDir, "hello.txt"));
      expect(structured.allowed).toBe(true);
      expect(structured.allowedRoots?.length).toBeGreaterThan(0);
    });

    it("should report per-path errors in batch metadata calls", async () => {
      const missingPath = path.join(testDir, "missing-info-batch.txt");
      const result = await client.callTool({
        name: "get_file_info",
        arguments: { paths: [path.join(testDir, "hello.txt"), missingPath], output_format: "both" },
      });

      expect(result.isError).toBeFalsy();
      const structured = result.structuredContent as { files?: Array<{ path: string; success: boolean; errorCode?: string }> };
      expect(structured.files?.[1]).toMatchObject({ path: missingPath, success: false, errorCode: "PATH_NOT_FOUND" });
    });
  });

  // --- list_allowed_directories ---
  describe("list_allowed_directories", () => {
    it("should list the test directory", async () => {
      const result = await client.callTool({ name: "list_allowed_directories", arguments: {} });
      const text = (result.content as ContentItem[])[0].text;
      expect(text).toContain("Allowed filesystem roots:");
    });
  });

  describe("exact file roots", () => {
    it("should allow an exact file root and reject siblings through tool calls", async () => {
      const previousRoots = getAllowedRoots();
      const allowedFile = path.join(testDir, "file-root-only.txt");
      const siblingFile = path.join(testDir, "file-root-sibling.txt");
      await fs.writeFile(allowedFile, "allowed file root");
      await fs.writeFile(siblingFile, "sibling should be denied");

      try {
        await updateAllowedDirectoriesFromRoots([{ uri: pathToFileURL(allowedFile).href }]);

        const allowed = await client.callTool({ name: "read_file", arguments: { path: allowedFile } });
        expect(allowed.isError).toBeFalsy();
        expect((allowed.content as ContentItem[])[0].text).toContain("allowed file root");

        const overwritten = await client.callTool({ name: "write_file", arguments: { path: allowedFile, content: "overwritten file root", overwrite: true } });
        expect(overwritten.isError).toBeFalsy();
        expect(await fs.readFile(allowedFile, "utf-8")).toBe("overwritten file root");

        const edited = await client.callTool({
          name: "edit_file",
          arguments: { path: allowedFile, edits: [{ oldText: "overwritten", newText: "edited" }] },
        });
        expect(edited.isError).toBeFalsy();
        expect(await fs.readFile(allowedFile, "utf-8")).toBe("edited file root");

        const sibling = await client.callTool({ name: "read_file", arguments: { path: siblingFile } });
        expect(sibling.isError).toBe(true);

        const fakeChild = await client.callTool({ name: "read_file", arguments: { path: path.join(allowedFile, "child.txt") } });
        expect(fakeChild.isError).toBe(true);
      } finally {
        setAllowedRoots(previousRoots);
      }
    });
  });

  // --- Integration edge cases ---
  describe("read_file edge cases", () => {
    it("should detect and strip UTF-8 BOM", async () => {
      const bomFile = path.join(testDir, "bom-test.txt");
      const bom = Buffer.from([0xEF, 0xBB, 0xBF]);
      const content = Buffer.from("BOM content here");
      await fs.writeFile(bomFile, Buffer.concat([bom, content]));
      const result = await client.callTool({ name: "read_file", arguments: { path: bomFile } });
      expect(result.isError).toBeFalsy();
      const text = (result.content as ContentItem[])[0].text;
      expect(text).toContain("BOM content here");
      // BOM detection info is in structuredContent result, not text
    });

    it("should return binary content with null bytes", async () => {
      const binFile = path.join(testDir, "binary-test.bin");
      await fs.writeFile(binFile, Buffer.from([0x00, 0x01, 0x02, 0x48, 0x65, 0x6C, 0x6C, 0x6F]));
      const result = await client.callTool({ name: "read_file", arguments: { path: binFile } });
      expect(result.isError).toBeFalsy();
      // Binary content warning is in result metadata; text still returned
      const text = (result.content as ContentItem[])[0].text;
      expect(text).toContain("Hello");
    });

    it("should error when start_line exceeds file length", async () => {
      const result = await client.callTool({ name: "read_file", arguments: { path: path.join(testDir, "hello.txt"), start_line: 999, end_line: 1000 } });
      expect(result.isError).toBe(true);
    });
  });

  describe("write_file edge cases", () => {
    it("should write with specific encoding", async () => {
      const encFile = path.join(testDir, "enc-write.txt");
      const result = await client.callTool({ name: "write_file", arguments: { path: encFile, content: "encoded content", encoding: "ascii" } });
      expect(result.isError).toBeFalsy();
      const content = await fs.readFile(encFile, "ascii");
      expect(content).toBe("encoded content");
    });
  });

  describe("edit_file edge cases", () => {
    it("should support encoding parameter", async () => {
      const encEditFile = path.join(testDir, "enc-edit.txt");
      await fs.writeFile(encEditFile, "find me");
      const result = await client.callTool({ name: "edit_file", arguments: { path: encEditFile, edits: [{ oldText: "find me", newText: "found you" }], encoding: "utf-8" } });
      expect(result.isError).toBeFalsy();
      expect(await fs.readFile(encEditFile, "utf-8")).toContain("found you");
    });
  });

  describe("read_media_file edge cases", () => {
    it("should handle file with unknown extension", async () => {
      const unknownFile = path.join(testDir, "data.xyz123");
      await fs.writeFile(unknownFile, "some binary-like content");
      const result = await client.callTool({ name: "read_media_file", arguments: { path: unknownFile } });
      expect(result.isError).toBeFalsy();
      const content = (result.content as ContentItem[])[0];
      expect(content.type).toBe("text");
      expect(content.text).toContain("base64 data omitted");
      expect(content.data).toBeUndefined();
    });
  });

  describe("rename_file edge cases", () => {
    it("should error for non-existent source", async () => {
      const result = await client.callTool({ name: "rename_file", arguments: { source: path.join(testDir, "no-exist-src.txt"), destination: path.join(testDir, "no-exist-dst.txt") } });
      expect(result.isError).toBe(true);
    });
  });

  describe("search_files edge cases", () => {
    it("should support excludePatterns", async () => {
      const result = await client.callTool({ name: "search_files", arguments: { path: testDir, pattern: "", excludePatterns: ["*.json"] } });
      const text = (result.content as ContentItem[])[0].text;
      expect(text).not.toContain("data.json");
    });
  });

  describe("get_file_info edge cases", () => {
    it("should resolve symlink and return target file info", async () => {
      const target = path.join(testDir, "info-target.txt");
      const link = path.join(testDir, "info-link.txt");
      await fs.writeFile(target, "target");
      try {
        await fs.symlink(target, link);
        // validatePath resolves symlinks via realpath, so get_file_info returns target info
        const result = await client.callTool({ name: "get_file_info", arguments: { path: link } });
        const text = (result.content as ContentItem[])[0].text;
        expect(text).toContain("isFile: true");
        expect(text).toContain("size: 6");
        expect(text).toContain("isSymlink: true");
        expect(text).toContain("symlinkTarget:");
        expect(text).toContain("resolvedSymlinkTarget:");
      } catch (e: unknown) {
        if (!hasErrorCode(e) || (e.code !== "EPERM" && e.code !== "EACCES")) throw e;
      }
    });

    it("should return error for non-existent path", async () => {
      const result = await client.callTool({ name: "get_file_info", arguments: { path: path.join(testDir, "nonexistent-info.txt") } });
      expect(result.isError).toBe(true);
    });
  });
});

// --- MCP Roots Helpers (unit tests for exported functions) ---
describe("MCP Roots helpers", () => {
  let rootsTestDir: string;

  beforeAll(async () => {
    const rawDir = await fs.mkdtemp(path.join(os.tmpdir(), "fs-mcp-roots-"));
    rootsTestDir = await fs.realpath(rawDir);
  });

  afterAll(async () => {
    await fs.rm(rootsTestDir, { recursive: true, force: true });
  });

  describe("parseRootUri", () => {
    it("should parse file:// URIs to absolute paths", async () => {
      const result = await parseRootUri(pathToFileURL(rootsTestDir).href);
      expect(result).toBeTruthy();
      expect(result).toContain(path.basename(rootsTestDir));
    });

    it("should parse encoded file:// URIs with spaces", async () => {
      const spacedDir = path.join(rootsTestDir, "dir with spaces");
      await fs.mkdir(spacedDir, { recursive: true });
      const result = await parseRootUri(pathToFileURL(spacedDir).href);
      expect(result).toBe(spacedDir);
    });

    it("should reject plain absolute paths because MCP roots must be file URIs", async () => {
      const result = await parseRootUri(rootsTestDir);
      expect(result).toBeNull();
    });

    it("should reject tilde paths because MCP roots must be file URIs", async () => {
      const result = await parseRootUri("~");
      expect(result).toBeNull();
    });

    it("should return null for non-existent paths", async () => {
      const result = await parseRootUri("/nonexistent/path/that/doesnt/exist");
      expect(result).toBeNull();
    });
  });

  describe("getValidRootDirectories", () => {
    it("should return valid directory roots", async () => {
      const roots = [{ uri: pathToFileURL(rootsTestDir).href }];
      const result = await getValidRootDirectories(roots);
      expect(result.length).toBe(1);
      expect(result[0]).toEqual({ path: rootsTestDir, kind: "directory" });
    });

    it("should skip invalid URIs", async () => {
      const roots = [{ uri: "file:///nonexistent/totally/fake/dir" }];
      const result = await getValidRootDirectories(roots);
      expect(result.length).toBe(0);
    });

    it("should return valid file roots", async () => {
      const filePath = path.join(rootsTestDir, "afile.txt");
      await fs.writeFile(filePath, "test");
      const roots = [{ uri: pathToFileURL(filePath).href }];
      const result = await getValidRootDirectories(roots);
      expect(result).toEqual([{ path: filePath, kind: "file" }]);
    });
  });

  describe("updateAllowedDirectoriesFromRoots", () => {
    it("should update allowed directories from valid roots", async () => {
      const original = getAllowedDirectories();
      await updateAllowedDirectoriesFromRoots([{ uri: pathToFileURL(rootsTestDir).href }]);
      const updated = getAllowedDirectories();
      expect(updated.length).toBeGreaterThan(0);
      // Restore
      setAllowedDirectories(original);
    });

    it("should not update if no valid roots provided", async () => {
      const original = getAllowedDirectories();
      const placeholder = path.join(os.tmpdir(), "original");
      setAllowedDirectories([placeholder]);
      await updateAllowedDirectoriesFromRoots([{ uri: "file:///nonexistent/fake" }]);
      // Should keep original since no valid roots
      expect(getAllowedDirectories()).toEqual([placeholder]);
      setAllowedDirectories(original);
    });
  });
});