feat(KB-104): move file browser from task modal to toolbar

- Add backend API routes and file service for project-scoped file operations
- Create useProjectFileBrowser and useProjectFileEditor hooks with comprehensive tests
- Update FileBrowserModal to support both task and project modes via dualMode prop
- Add Files button to dashboard header toolbar
- Remove Files tab from TaskDetailModal
- Integrate project file browser into main App layout
- Include changeset for @dustinbyrne/kb package

packages/dashboard/app/hooks/__tests__/useProjectFileBrowser.test.ts

@@ -0,0 +1,181 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, act, waitFor } from "@testing-library/react";
+import { useProjectFileBrowser } from "../useProjectFileBrowser";
+import * as api from "../../api";
+import type { FileListResponse } from "../../api";
+
+// Mock the api module
+vi.mock("../../api", () => ({
+  fetchProjectFileList: vi.fn(),
+}));
+
+const mockFetchProjectFileList = vi.mocked(api.fetchProjectFileList);
+
+describe("useProjectFileBrowser", () => {
+  beforeEach(() => {
+    mockFetchProjectFileList.mockReset();
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("initializes with empty entries and loading false when disabled", () => {
+    const { result } = renderHook(() => useProjectFileBrowser("/project", false));
+
+    expect(result.current.entries).toEqual([]);
+    expect(result.current.loading).toBe(false);
+    expect(result.current.error).toBeNull();
+    expect(result.current.currentPath).toBe(".");
+  });
+
+  it("fetches file list when enabled", async () => {
+    const mockResponse: FileListResponse = {
+      path: ".",
+      entries: [
+        { name: "src", type: "directory", mtime: "2024-01-01T00:00:00Z" },
+        { name: "package.json", type: "file", size: 100, mtime: "2024-01-01T00:00:00Z" },
+      ],
+    };
+    mockFetchProjectFileList.mockResolvedValueOnce(mockResponse);
+
+    const { result } = renderHook(() => useProjectFileBrowser("/project", true));
+
+    // Should start loading
+    expect(result.current.loading).toBe(true);
+
+    // Wait for fetch to complete
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(result.current.entries).toHaveLength(2);
+    expect(result.current.entries[0].name).toBe("src");
+    expect(result.current.entries[1].name).toBe("package.json");
+    expect(mockFetchProjectFileList).toHaveBeenCalledWith(undefined);
+  });
+
+  it("fetches subdirectory when path changes", async () => {
+    const rootResponse: FileListResponse = {
+      path: ".",
+      entries: [{ name: "src", type: "directory", mtime: "2024-01-01T00:00:00Z" }],
+    };
+    const subdirResponse: FileListResponse = {
+      path: "src",
+      entries: [{ name: "index.ts", type: "file", size: 200, mtime: "2024-01-01T00:00:00Z" }],
+    };
+
+    mockFetchProjectFileList
+      .mockResolvedValueOnce(rootResponse)
+      .mockResolvedValueOnce(subdirResponse);
+
+    const { result } = renderHook(() => useProjectFileBrowser("/project", true));
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.entries).toHaveLength(1);
+
+    // Navigate to subdirectory
+    act(() => {
+      result.current.setPath("src");
+    });
+
+    await waitFor(() => expect(result.current.currentPath).toBe("src"));
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(mockFetchProjectFileList).toHaveBeenLastCalledWith("src");
+  });
+
+  it("handles fetch errors", async () => {
+    mockFetchProjectFileList.mockRejectedValueOnce(new Error("Failed to load files"));
+
+    const { result } = renderHook(() => useProjectFileBrowser("/project", true));
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(result.current.error).toBe("Failed to load files");
+    expect(result.current.entries).toEqual([]);
+  });
+
+  it("refreshes file list when refresh is called", async () => {
+    const initialResponse: FileListResponse = {
+      path: ".",
+      entries: [{ name: "file1.txt", type: "file", size: 100, mtime: "2024-01-01T00:00:00Z" }],
+    };
+    const refreshedResponse: FileListResponse = {
+      path: ".",
+      entries: [
+        { name: "file1.txt", type: "file", size: 100, mtime: "2024-01-01T00:00:00Z" },
+        { name: "file2.txt", type: "file", size: 200, mtime: "2024-01-02T00:00:00Z" },
+      ],
+    };
+
+    mockFetchProjectFileList
+      .mockResolvedValueOnce(initialResponse)
+      .mockResolvedValueOnce(refreshedResponse);
+
+    const { result } = renderHook(() => useProjectFileBrowser("/project", true));
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.entries).toHaveLength(1);
+
+    // Refresh
+    act(() => {
+      result.current.refresh();
+    });
+
+    await waitFor(() => expect(result.current.entries).toHaveLength(2));
+    expect(mockFetchProjectFileList).toHaveBeenCalledTimes(2);
+  });
+
+  it("clears error when path changes", async () => {
+    mockFetchProjectFileList
+      .mockRejectedValueOnce(new Error("Failed to load files"))
+      .mockResolvedValueOnce({
+        path: ".",
+        entries: [{ name: "file.txt", type: "file", size: 100, mtime: "2024-01-01T00:00:00Z" }],
+      });
+
+    const { result } = renderHook(() => useProjectFileBrowser("/project", true));
+
+    await waitFor(() => expect(result.current.error).toBe("Failed to load files"));
+
+    // Change path should clear error
+    act(() => {
+      result.current.setPath("subdir");
+    });
+
+    expect(result.current.error).toBeNull();
+  });
+
+  it("does not fetch when disabled", async () => {
+    renderHook(() => useProjectFileBrowser("/project", false));
+
+    // Wait a bit to ensure no fetch happens
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(mockFetchProjectFileList).not.toHaveBeenCalled();
+  });
+
+  it("cancels in-flight requests on unmount", async () => {
+    let resolveFetch: (value: FileListResponse) => void;
+    const fetchPromise = new Promise<FileListResponse>((resolve) => {
+      resolveFetch = resolve;
+    });
+    mockFetchProjectFileList.mockReturnValueOnce(fetchPromise);
+
+    const { unmount } = renderHook(() => useProjectFileBrowser("/project", true));
+
+    // Unmount before fetch completes
+    unmount();
+
+    // Complete the fetch after unmount
+    resolveFetch!({
+      path: ".",
+      entries: [{ name: "file.txt", type: "file", size: 100, mtime: "2024-01-01T00:00:00Z" }],
+    });
+
+    // Wait a bit to ensure state update doesn't happen
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    // Should not throw or have any issues
+    expect(mockFetchProjectFileList).toHaveBeenCalledTimes(1);
+  });
+});

packages/dashboard/app/hooks/__tests__/useProjectFileEditor.test.ts

@@ -0,0 +1,324 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, act, waitFor } from "@testing-library/react";
+import { useProjectFileEditor } from "../useProjectFileEditor";
+import * as api from "../../api";
+import type { FileContentResponse, SaveFileResponse } from "../../api";
+
+// Mock the api module
+vi.mock("../../api", () => ({
+  fetchProjectFileContent: vi.fn(),
+  saveProjectFileContent: vi.fn(),
+}));
+
+const mockFetchProjectFileContent = vi.mocked(api.fetchProjectFileContent);
+const mockSaveProjectFileContent = vi.mocked(api.saveProjectFileContent);
+
+describe("useProjectFileEditor", () => {
+  beforeEach(() => {
+    mockFetchProjectFileContent.mockReset();
+    mockSaveProjectFileContent.mockReset();
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("initializes with empty content when no file selected", () => {
+    const { result } = renderHook(() => useProjectFileEditor("/project", null, true));
+
+    expect(result.current.content).toBe("");
+    expect(result.current.originalContent).toBe("");
+    expect(result.current.loading).toBe(false);
+    expect(result.current.error).toBeNull();
+    expect(result.current.hasChanges).toBe(false);
+    expect(result.current.mtime).toBeNull();
+  });
+
+  it("initializes with empty content when disabled", () => {
+    const { result } = renderHook(() => useProjectFileEditor("/project", "src/index.ts", false));
+
+    expect(result.current.content).toBe("");
+    expect(result.current.loading).toBe(false);
+    expect(mockFetchProjectFileContent).not.toHaveBeenCalled();
+  });
+
+  it("fetches file content when filePath is provided and enabled", async () => {
+    const mockResponse: FileContentResponse = {
+      content: "console.log('hello');",
+      mtime: "2024-01-01T00:00:00Z",
+      size: 21,
+    };
+    mockFetchProjectFileContent.mockResolvedValueOnce(mockResponse);
+
+    const { result } = renderHook(() => useProjectFileEditor("/project", "src/index.ts", true));
+
+    expect(result.current.loading).toBe(true);
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(result.current.content).toBe("console.log('hello');");
+    expect(result.current.originalContent).toBe("console.log('hello');");
+    expect(result.current.mtime).toBe("2024-01-01T00:00:00Z");
+    expect(result.current.hasChanges).toBe(false);
+    expect(mockFetchProjectFileContent).toHaveBeenCalledWith("src/index.ts");
+  });
+
+  it("tracks content changes", async () => {
+    const mockResponse: FileContentResponse = {
+      content: "console.log('hello');",
+      mtime: "2024-01-01T00:00:00Z",
+      size: 21,
+    };
+    mockFetchProjectFileContent.mockResolvedValueOnce(mockResponse);
+
+    const { result } = renderHook(() => useProjectFileEditor("/project", "src/index.ts", true));
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.hasChanges).toBe(false);
+
+    // Edit content
+    act(() => {
+      result.current.setContent("console.log('world');");
+    });
+
+    expect(result.current.content).toBe("console.log('world');");
+    expect(result.current.hasChanges).toBe(true);
+  });
+
+  it("saves file content", async () => {
+    const loadResponse: FileContentResponse = {
+      content: "console.log('hello');",
+      mtime: "2024-01-01T00:00:00Z",
+      size: 21,
+    };
+    const saveResponse: SaveFileResponse = {
+      success: true,
+      mtime: "2024-01-02T00:00:00Z",
+      size: 22,
+    };
+
+    mockFetchProjectFileContent.mockResolvedValueOnce(loadResponse);
+    mockSaveProjectFileContent.mockResolvedValueOnce(saveResponse);
+
+    const { result } = renderHook(() => useProjectFileEditor("/project", "src/index.ts", true));
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    // Edit and save
+    act(() => {
+      result.current.setContent("console.log('world');");
+    });
+
+    await act(async () => {
+      await result.current.save();
+    });
+
+    expect(mockSaveProjectFileContent).toHaveBeenCalledWith("src/index.ts", "console.log('world');");
+    expect(result.current.originalContent).toBe("console.log('world');");
+    expect(result.current.hasChanges).toBe(false);
+    expect(result.current.mtime).toBe("2024-01-02T00:00:00Z");
+  });
+
+  it("does not save when there are no changes", async () => {
+    const mockResponse: FileContentResponse = {
+      content: "console.log('hello');",
+      mtime: "2024-01-01T00:00:00Z",
+      size: 21,
+    };
+    mockFetchProjectFileContent.mockResolvedValueOnce(mockResponse);
+
+    const { result } = renderHook(() => useProjectFileEditor("/project", "src/index.ts", true));
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    // Try to save without changes
+    await act(async () => {
+      await result.current.save();
+    });
+
+    expect(mockSaveProjectFileContent).not.toHaveBeenCalled();
+  });
+
+  it("handles fetch errors", async () => {
+    mockFetchProjectFileContent.mockRejectedValueOnce(new Error("File not found"));
+
+    const { result } = renderHook(() => useProjectFileEditor("/project", "src/missing.ts", true));
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    expect(result.current.error).toBe("File not found");
+    expect(result.current.content).toBe("");
+  });
+
+  it("handles save errors", async () => {
+    const loadResponse: FileContentResponse = {
+      content: "console.log('hello');",
+      mtime: "2024-01-01T00:00:00Z",
+      size: 21,
+    };
+    mockFetchProjectFileContent.mockResolvedValueOnce(loadResponse);
+    mockSaveProjectFileContent.mockRejectedValueOnce(new Error("Permission denied"));
+
+    const { result } = renderHook(() => useProjectFileEditor("/project", "src/index.ts", true));
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    // Edit and try to save
+    act(() => {
+      result.current.setContent("console.log('world');");
+    });
+
+    let saveError: Error | undefined;
+    await act(async () => {
+      try {
+        await result.current.save();
+      } catch (err) {
+        saveError = err as Error;
+      }
+    });
+
+    expect(saveError?.message).toBe("Permission denied");
+    expect(result.current.error).toBe("Permission denied");
+    // Original content should not be updated on error
+    expect(result.current.originalContent).toBe("console.log('hello');");
+    expect(result.current.hasChanges).toBe(true);
+  });
+
+  it("clears content when filePath changes", async () => {
+    const firstResponse: FileContentResponse = {
+      content: "// file 1",
+      mtime: "2024-01-01T00:00:00Z",
+      size: 10,
+    };
+    const secondResponse: FileContentResponse = {
+      content: "// file 2",
+      mtime: "2024-01-02T00:00:00Z",
+      size: 10,
+    };
+
+    mockFetchProjectFileContent
+      .mockResolvedValueOnce(firstResponse)
+      .mockResolvedValueOnce(secondResponse);
+
+    const { result, rerender } = renderHook(
+      ({ filePath }) => useProjectFileEditor("/project", filePath, true),
+      { initialProps: { filePath: "file1.ts" } }
+    );
+
+    await waitFor(() => expect(result.current.content).toBe("// file 1"));
+
+    // Change file
+    rerender({ filePath: "file2.ts" });
+
+    await waitFor(() => expect(result.current.content).toBe("// file 2"));
+  });
+
+  it("clears content when disabled", async () => {
+    const mockResponse: FileContentResponse = {
+      content: "console.log('hello');",
+      mtime: "2024-01-01T00:00:00Z",
+      size: 21,
+    };
+    mockFetchProjectFileContent.mockResolvedValueOnce(mockResponse);
+
+    const { result, rerender } = renderHook(
+      ({ enabled }) => useProjectFileEditor("/project", "src/index.ts", enabled),
+      { initialProps: { enabled: true } }
+    );
+
+    await waitFor(() => expect(result.current.content).toBe("console.log('hello');"));
+
+    // Disable
+    rerender({ enabled: false });
+
+    expect(result.current.content).toBe("");
+    expect(result.current.originalContent).toBe("");
+    expect(result.current.mtime).toBeNull();
+  });
+
+  it("clears error when content is edited", async () => {
+    mockFetchProjectFileContent.mockRejectedValueOnce(new Error("File not found"));
+
+    const { result } = renderHook(() => useProjectFileEditor("/project", "src/missing.ts", true));
+
+    await waitFor(() => expect(result.current.error).toBe("File not found"));
+
+    // Edit content should clear error
+    act(() => {
+      result.current.setContent("new content");
+    });
+
+    expect(result.current.error).toBeNull();
+  });
+
+  it("shows saving state during save operation", async () => {
+    const loadResponse: FileContentResponse = {
+      content: "console.log('hello');",
+      mtime: "2024-01-01T00:00:00Z",
+      size: 21,
+    };
+    const saveResponse: SaveFileResponse = {
+      success: true,
+      mtime: "2024-01-02T00:00:00Z",
+      size: 22,
+    };
+
+    let resolveSave: (value: SaveFileResponse) => void;
+    const savePromise = new Promise<SaveFileResponse>((resolve) => {
+      resolveSave = resolve;
+    });
+
+    mockFetchProjectFileContent.mockResolvedValueOnce(loadResponse);
+    mockSaveProjectFileContent.mockReturnValueOnce(savePromise);
+
+    const { result } = renderHook(() => useProjectFileEditor("/project", "src/index.ts", true));
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    // Edit and save
+    act(() => {
+      result.current.setContent("console.log('world');");
+    });
+
+    // Start save
+    let savePromiseResolved = false;
+    act(() => {
+      result.current.save().then(() => {
+        savePromiseResolved = true;
+      });
+    });
+
+    expect(result.current.saving).toBe(true);
+
+    // Complete save
+    resolveSave!(saveResponse);
+    await waitFor(() => expect(savePromiseResolved).toBe(true));
+
+    expect(result.current.saving).toBe(false);
+  });
+
+  it("cancels in-flight fetch on unmount", async () => {
+    let resolveFetch: (value: FileContentResponse) => void;
+    const fetchPromise = new Promise<FileContentResponse>((resolve) => {
+      resolveFetch = resolve;
+    });
+    mockFetchProjectFileContent.mockReturnValueOnce(fetchPromise);
+
+    const { unmount } = renderHook(() => useProjectFileEditor("/project", "src/index.ts", true));
+
+    // Unmount before fetch completes
+    unmount();
+
+    // Complete the fetch after unmount
+    resolveFetch!({
+      content: "console.log('hello');",
+      mtime: "2024-01-01T00:00:00Z",
+      size: 21,
+    });
+
+    // Wait a bit to ensure state update doesn't happen
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(mockFetchProjectFileContent).toHaveBeenCalledTimes(1);
+  });
+});

packages/dashboard/app/hooks/useProjectFileBrowser.ts

@@ -0,0 +1,83 @@
+import { useState, useEffect, useCallback } from "react";
+import type { FileNode, FileListResponse } from "../api";
+import { fetchProjectFileList } from "../api";
+
+interface UseProjectFileBrowserReturn {
+  entries: FileNode[];
+  currentPath: string;
+  setPath: (path: string) => void;
+  loading: boolean;
+  error: string | null;
+  refresh: () => void;
+}
+
+/**
+ * Hook for browsing files in the project root directory.
+ *
+ * @param rootPath - The project root directory path (from config/store)
+ * @param enabled - Whether to enable fetching (e.g., when modal is open)
+ * @returns File browser state and controls
+ */
+export function useProjectFileBrowser(rootPath: string, enabled: boolean): UseProjectFileBrowserReturn {
+  const [entries, setEntries] = useState<FileNode[]>([]);
+  const [currentPath, setCurrentPath] = useState<string>(".");
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [refreshKey, setRefreshKey] = useState(0);
+
+  const refresh = useCallback(() => {
+    setRefreshKey((k) => k + 1);
+  }, []);
+
+  const setPath = useCallback((path: string) => {
+    setCurrentPath(path);
+    setError(null);
+  }, []);
+
+  useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+
+    let cancelled = false;
+
+    async function loadFiles() {
+      setLoading(true);
+      setError(null);
+
+      try {
+        const response: FileListResponse = await fetchProjectFileList(
+          currentPath === "." ? undefined : currentPath
+        );
+
+        if (!cancelled) {
+          setEntries(response.entries);
+        }
+      } catch (err: any) {
+        if (!cancelled) {
+          setError(err.message || "Failed to load files");
+          setEntries([]);
+        }
+      } finally {
+        if (!cancelled) {
+          setLoading(false);
+        }
+      }
+    }
+
+    loadFiles();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [currentPath, enabled, refreshKey]);
+
+  return {
+    entries,
+    currentPath,
+    setPath,
+    loading,
+    error,
+    refresh,
+  };
+}

packages/dashboard/app/hooks/useProjectFileEditor.ts

@@ -0,0 +1,120 @@
+import { useState, useEffect, useCallback } from "react";
+import type { FileContentResponse, SaveFileResponse } from "../api";
+import { fetchProjectFileContent, saveProjectFileContent } from "../api";
+
+interface UseProjectFileEditorReturn {
+  content: string;
+  setContent: (content: string) => void;
+  originalContent: string;
+  loading: boolean;
+  saving: boolean;
+  error: string | null;
+  save: () => Promise<void>;
+  hasChanges: boolean;
+  mtime: string | null;
+}
+
+/**
+ * Hook for editing a file in the project directory.
+ *
+ * @param rootPath - The project root directory path (from config/store)
+ * @param filePath - The file path to edit (null if no file selected)
+ * @param enabled - Whether to enable loading (e.g., when editor is visible)
+ * @returns File editor state and controls
+ */
+export function useProjectFileEditor(
+  rootPath: string,
+  filePath: string | null,
+  enabled: boolean
+): UseProjectFileEditorReturn {
+  const [content, setContentState] = useState<string>("");
+  const [originalContent, setOriginalContent] = useState<string>("");
+  const [mtime, setMtime] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const setContent = useCallback((newContent: string) => {
+    setContentState(newContent);
+    setError(null);
+  }, []);
+
+  // Load file content when filePath changes
+  useEffect(() => {
+    if (!enabled || !filePath) {
+      setContentState("");
+      setOriginalContent("");
+      setMtime(null);
+      setError(null);
+      return;
+    }
+
+    let cancelled = false;
+
+    async function loadFile() {
+      setLoading(true);
+      setError(null);
+
+      try {
+        const response: FileContentResponse = await fetchProjectFileContent(filePath!);
+
+        if (!cancelled) {
+          setContentState(response.content);
+          setOriginalContent(response.content);
+          setMtime(response.mtime);
+        }
+      } catch (err: any) {
+        if (!cancelled) {
+          setError(err.message || "Failed to load file");
+          setContentState("");
+          setOriginalContent("");
+          setMtime(null);
+        }
+      } finally {
+        if (!cancelled) {
+          setLoading(false);
+        }
+      }
+    }
+
+    loadFile();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [filePath, enabled]);
+
+  const hasChanges = content !== originalContent;
+
+  const save = useCallback(async () => {
+    if (!filePath || !hasChanges) {
+      return;
+    }
+
+    setSaving(true);
+    setError(null);
+
+    try {
+      const response: SaveFileResponse = await saveProjectFileContent(filePath, content);
+      setOriginalContent(content);
+      setMtime(response.mtime);
+    } catch (err: any) {
+      setError(err.message || "Failed to save file");
+      throw err;
+    } finally {
+      setSaving(false);
+    }
+  }, [filePath, content, hasChanges]);
+
+  return {
+    content,
+    setContent,
+    originalContent,
+    loading,
+    saving,
+    error,
+    save,
+    hasChanges,
+    mtime,
+  };
+}