relay-ide 0.1.0

package/dist/test/server/workspaces.js

@@ -0,0 +1,657 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { Router } from 'express';
+import { loadConfig, saveConfig, getWorkspaceSettings, setWorkspaceSettings, deleteWorkspaceSettingKeys } from './config.js';
+import { trackEvent } from './analytics.js';
+import { listBranches, getActivityFeed, getCiStatus, getPrForBranch, getUnresolvedCommentCount, switchBranch, getCurrentBranch } from './git.js';
+import { MOUNTAIN_NAMES } from './types.js';
+const execFileAsync = promisify(execFile);
+const BROWSE_DENYLIST = new Set([
+    'node_modules', '.git', '.Trash', '__pycache__',
+    '.cache', '.npm', '.yarn', '.nvm',
+]);
+const BROWSE_MAX_ENTRIES = 100;
+const BULK_MAX_PATHS = 50;
+// Exported helpers
+/**
+ * Resolves and validates a raw workspace path string.
+ * Throws with a human-readable message if the path is invalid.
+ */
+export async function validateWorkspacePath(rawPath) {
+    if (!rawPath || typeof rawPath !== 'string') {
+        throw new Error('Path must be a non-empty string');
+    }
+    const resolved = path.resolve(rawPath);
+    let stat;
+    try {
+        stat = await fs.promises.stat(resolved);
+    }
+    catch {
+        throw new Error(`Path does not exist: ${resolved}`);
+    }
+    if (!stat.isDirectory()) {
+        throw new Error(`Path is not a directory: ${resolved}`);
+    }
+    return resolved;
+}
+/**
+ * Detects whether a directory is the root of a git repository and, if so,
+ * what the default branch name is.
+ */
+export async function detectGitRepo(dirPath, execAsync = execFileAsync) {
+    try {
+        await execAsync('git', ['rev-parse', '--git-dir'], { cwd: dirPath });
+    }
+    catch {
+        return { isGitRepo: false, defaultBranch: null };
+    }
+    // Attempt to determine the default branch from remote HEAD
+    let defaultBranch = null;
+    try {
+        const { stdout } = await execAsync('git', ['symbolic-ref', 'refs/remotes/origin/HEAD', '--short'], { cwd: dirPath });
+        const trimmed = stdout.trim();
+        // "origin/main" → "main"
+        defaultBranch = trimmed.replace(/^origin\//, '') || null;
+    }
+    catch {
+        // Fall back to checking local HEAD
+        try {
+            const { stdout } = await execAsync('git', ['symbolic-ref', '--short', 'HEAD'], { cwd: dirPath });
+            defaultBranch = stdout.trim() || null;
+        }
+        catch {
+            // Cannot determine default branch
+        }
+    }
+    return { isGitRepo: true, defaultBranch };
+}
+// Router factory
+/**
+ * Creates and returns an Express Router that handles all /workspaces routes.
+ *
+ * Caller is responsible for mounting and applying auth middleware:
+ *   app.use('/workspaces', requireAuth, createWorkspaceRouter({ configPath }));
+ */
+export function createWorkspaceRouter(deps) {
+    const { configPath } = deps;
+    const exec = deps.execAsync ?? execFileAsync;
+    const router = Router();
+    // Helper: reload config on every request so concurrent changes are reflected
+    function getConfig() {
+        return loadConfig(configPath);
+    }
+    // GET /workspaces — list all workspaces with git info
+    router.get('/', async (_req, res) => {
+        const config = getConfig();
+        const workspacePaths = config.workspaces ?? [];
+        const results = await Promise.all(workspacePaths.map(async (p) => {
+            const name = path.basename(p);
+            const { isGitRepo, defaultBranch } = await detectGitRepo(p, exec);
+            return { path: p, name, isGitRepo, defaultBranch };
+        }));
+        res.json({ workspaces: results });
+    });
+    // POST /workspaces — add a workspace
+    router.post('/', async (req, res) => {
+        const body = req.body;
+        const rawPath = body.path;
+        if (typeof rawPath !== 'string' || !rawPath) {
+            res.status(400).json({ error: 'path is required' });
+            return;
+        }
+        let resolved;
+        try {
+            resolved = await validateWorkspacePath(rawPath);
+        }
+        catch (err) {
+            res.status(400).json({ error: err instanceof Error ? err.message : String(err) });
+            return;
+        }
+        const config = getConfig();
+        const workspaces = config.workspaces ?? [];
+        if (workspaces.includes(resolved)) {
+            res.status(409).json({ error: 'Workspace already exists' });
+            return;
+        }
+        const { isGitRepo, defaultBranch } = await detectGitRepo(resolved, exec);
+        config.workspaces = [...workspaces, resolved];
+        // Store detected default branch in per-workspace settings
+        if (isGitRepo && defaultBranch) {
+            if (!config.workspaceSettings)
+                config.workspaceSettings = {};
+            config.workspaceSettings[resolved] = {
+                ...config.workspaceSettings[resolved],
+                defaultBranch,
+            };
+        }
+        saveConfig(configPath, config);
+        trackEvent({ category: 'workspace', action: 'added', target: resolved, properties: { name: path.basename(resolved) } });
+        const workspace = {
+            path: resolved,
+            name: path.basename(resolved),
+            isGitRepo,
+            defaultBranch,
+        };
+        res.status(201).json(workspace);
+    });
+    // DELETE /workspaces — remove a workspace
+    router.delete('/', async (req, res) => {
+        const body = req.body;
+        const rawPath = body.path;
+        if (typeof rawPath !== 'string' || !rawPath) {
+            res.status(400).json({ error: 'path is required' });
+            return;
+        }
+        const resolved = path.resolve(rawPath);
+        const config = getConfig();
+        const workspaces = config.workspaces ?? [];
+        const idx = workspaces.indexOf(resolved);
+        if (idx === -1) {
+            res.status(404).json({ error: 'Workspace not found' });
+            return;
+        }
+        config.workspaces = workspaces.filter((p) => p !== resolved);
+        saveConfig(configPath, config);
+        trackEvent({ category: 'workspace', action: 'removed', target: resolved });
+        res.json({ removed: resolved });
+    });
+    // PUT /workspaces/reorder — reorder workspaces
+    router.put('/reorder', async (req, res) => {
+        const body = req.body;
+        const rawPaths = body.paths;
+        if (!Array.isArray(rawPaths)) {
+            res.status(400).json({ error: 'paths array is required' });
+            return;
+        }
+        const config = getConfig();
+        const current = config.workspaces ?? [];
+        // Validate that the submitted paths are the same set as the current workspaces
+        if (rawPaths.length !== current.length) {
+            res.status(400).json({ error: 'paths must contain the same set of workspaces as the current configuration' });
+            return;
+        }
+        const currentSet = new Set(current);
+        for (const p of rawPaths) {
+            if (typeof p !== 'string' || !currentSet.has(p)) {
+                res.status(400).json({ error: 'paths must contain the same set of workspaces as the current configuration' });
+                return;
+            }
+        }
+        config.workspaces = rawPaths;
+        saveConfig(configPath, config);
+        const results = await Promise.all(rawPaths.map(async (p) => {
+            const name = path.basename(p);
+            const { isGitRepo, defaultBranch } = await detectGitRepo(p, exec);
+            return { path: p, name, isGitRepo, defaultBranch };
+        }));
+        res.json({ workspaces: results });
+    });
+    // POST /workspaces/bulk — add multiple workspaces at once
+    router.post('/bulk', async (req, res) => {
+        const body = req.body;
+        const rawPaths = body.paths;
+        if (!Array.isArray(rawPaths) || rawPaths.length === 0) {
+            res.status(400).json({ error: 'paths array is required' });
+            return;
+        }
+        if (rawPaths.length > BULK_MAX_PATHS) {
+            res.status(400).json({ error: `Too many paths (max ${BULK_MAX_PATHS})` });
+            return;
+        }
+        const config = getConfig();
+        const existing = new Set(config.workspaces ?? []);
+        const added = [];
+        const errors = [];
+        for (const rawPath of rawPaths) {
+            if (typeof rawPath !== 'string' || !rawPath) {
+                errors.push({ path: String(rawPath), error: 'Invalid path' });
+                continue;
+            }
+            let resolved;
+            try {
+                resolved = await validateWorkspacePath(rawPath);
+            }
+            catch (err) {
+                errors.push({ path: rawPath, error: err instanceof Error ? err.message : String(err) });
+                continue;
+            }
+            if (existing.has(resolved)) {
+                errors.push({ path: rawPath, error: 'Already exists' });
+                continue;
+            }
+            const { isGitRepo, defaultBranch } = await detectGitRepo(resolved, exec);
+            existing.add(resolved);
+            added.push({ path: resolved, name: path.basename(resolved), isGitRepo, defaultBranch });
+            // Store detected default branch in per-workspace settings
+            if (isGitRepo && defaultBranch) {
+                if (!config.workspaceSettings)
+                    config.workspaceSettings = {};
+                config.workspaceSettings[resolved] = {
+                    ...config.workspaceSettings[resolved],
+                    defaultBranch,
+                };
+            }
+        }
+        if (added.length > 0) {
+            config.workspaces = [...(config.workspaces ?? []), ...added.map((a) => a.path)];
+            saveConfig(configPath, config);
+        }
+        res.status(201).json({ added, errors });
+    });
+    // GET /workspaces/dashboard — aggregated PR + activity data for a workspace
+    router.get('/dashboard', async (req, res) => {
+        const workspacePath = typeof req.query.path === 'string' ? req.query.path : undefined;
+        if (!workspacePath) {
+            res.status(400).json({ error: 'path query parameter is required' });
+            return;
+        }
+        const fields = 'number,title,url,headRefName,baseRefName,state,author,updatedAt,additions,deletions,reviewDecision,mergeable,mergeStateStatus';
+        // Get current GitHub user
+        let currentUser = '';
+        try {
+            const { stdout: whoami } = await exec('gh', ['api', 'user', '--jq', '.login'], { cwd: workspacePath });
+            currentUser = whoami.trim();
+        }
+        catch {
+            const response = { prs: [], error: 'gh_not_authenticated' };
+            res.json({ pullRequests: response, branches: [] });
+            return;
+        }
+        // Helper to map raw gh JSON to PullRequest
+        function mapRawPr(raw, role, fallbackAuthor) {
+            return {
+                number: raw.number,
+                title: raw.title,
+                url: raw.url,
+                headRefName: raw.headRefName,
+                baseRefName: raw.baseRefName ?? '',
+                state: raw.state,
+                author: raw.author?.login ?? fallbackAuthor,
+                role,
+                updatedAt: raw.updatedAt,
+                additions: raw.additions ?? 0,
+                deletions: raw.deletions ?? 0,
+                reviewDecision: raw.reviewDecision ?? null,
+                mergeable: raw.mergeable ?? null,
+            };
+        }
+        // Fetch authored + review-requested PRs in parallel
+        const [authored, reviewing] = await Promise.all([
+            (async () => {
+                try {
+                    const { stdout } = await exec('gh', ['pr', 'list', '--author', currentUser, '--state', 'open', '--limit', '30', '--json', fields], { cwd: workspacePath });
+                    return JSON.parse(stdout).map(pr => mapRawPr(pr, 'author', currentUser));
+                }
+                catch {
+                    return [];
+                }
+            })(),
+            (async () => {
+                try {
+                    const { stdout } = await exec('gh', ['pr', 'list', '--search', `review-requested:${currentUser}`, '--state', 'open', '--limit', '30', '--json', fields], { cwd: workspacePath });
+                    return JSON.parse(stdout).map(pr => mapRawPr(pr, 'reviewer', ''));
+                }
+                catch {
+                    return [];
+                }
+            })(),
+        ]);
+        // Deduplicate: if a PR appears in both, keep as 'author'
+        const seen = new Set(authored.map((pr) => pr.number));
+        const combined = [...authored, ...reviewing.filter((pr) => !seen.has(pr.number))];
+        // Sort by updatedAt descending
+        combined.sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime());
+        const pullRequests = { prs: combined };
+        // Fetch branches for the workspace
+        let branches = [];
+        try {
+            branches = await listBranches(workspacePath);
+        }
+        catch { /* not a git repo or git unavailable */ }
+        // Fetch recent activity
+        let activity = [];
+        try {
+            activity = await getActivityFeed(workspacePath);
+        }
+        catch { /* git log unavailable */ }
+        res.json({
+            pullRequests,
+            branches,
+            activity,
+        });
+    });
+    function buildMergedSettings(config, workspacePath) {
+        const resolved = path.resolve(workspacePath);
+        const wsOverrides = config.workspaceSettings?.[resolved] ?? {};
+        const effective = getWorkspaceSettings(config, resolved);
+        const overridden = [];
+        for (const key of ['defaultAgent', 'defaultContinue', 'defaultYolo', 'launchInTmux']) {
+            if (wsOverrides[key] !== undefined)
+                overridden.push(key);
+        }
+        return { settings: effective, overridden };
+    }
+    // GET /workspaces/settings — per-workspace overrides only
+    router.get('/settings', async (req, res) => {
+        const workspacePath = typeof req.query.path === 'string' ? req.query.path : undefined;
+        if (!workspacePath) {
+            res.status(400).json({ error: 'path query parameter is required' });
+            return;
+        }
+        // Backward compat: handle merged=true inline (same logic as /settings/merged)
+        if (req.query.merged === 'true') {
+            res.json(buildMergedSettings(getConfig(), workspacePath));
+            return;
+        }
+        const config = getConfig();
+        const resolved = path.resolve(workspacePath);
+        const settings = config.workspaceSettings?.[resolved] ?? {};
+        res.json(settings);
+    });
+    // GET /workspaces/settings/merged — effective settings with override tracking
+    router.get('/settings/merged', async (req, res) => {
+        const workspacePath = typeof req.query.path === 'string' ? req.query.path : undefined;
+        if (!workspacePath) {
+            res.status(400).json({ error: 'path query parameter is required' });
+            return;
+        }
+        res.json(buildMergedSettings(getConfig(), workspacePath));
+    });
+    // PATCH /workspaces/settings — update per-workspace settings
+    router.patch('/settings', async (req, res) => {
+        const workspacePath = typeof req.query.path === 'string' ? req.query.path : undefined;
+        if (!workspacePath) {
+            res.status(400).json({ error: 'path query parameter is required' });
+            return;
+        }
+        const resolved = path.resolve(workspacePath);
+        const updates = req.body;
+        const config = getConfig();
+        // Separate null values (deletions) from actual updates
+        const keysToDelete = [];
+        const keysToUpdate = {};
+        for (const [key, value] of Object.entries(updates)) {
+            if (value === null) {
+                keysToDelete.push(key);
+            }
+            else {
+                keysToUpdate[key] = value;
+            }
+        }
+        // Apply deletions first
+        if (keysToDelete.length > 0) {
+            deleteWorkspaceSettingKeys(configPath, config, resolved, keysToDelete);
+        }
+        // Apply updates
+        if (Object.keys(keysToUpdate).length > 0) {
+            setWorkspaceSettings(configPath, config, resolved, keysToUpdate);
+        }
+        // Return the current raw workspace settings
+        const final = config.workspaceSettings?.[resolved] ?? {};
+        res.json(final);
+    });
+    // GET /workspaces/pr — PR info for a specific branch
+    router.get('/pr', async (req, res) => {
+        const workspacePath = typeof req.query.path === 'string' ? req.query.path : undefined;
+        const branch = typeof req.query.branch === 'string' ? req.query.branch : undefined;
+        if (!workspacePath || !branch) {
+            res.status(400).json({ error: 'path and branch query parameters are required' });
+            return;
+        }
+        try {
+            const pr = await getPrForBranch(workspacePath, branch);
+            if (pr) {
+                if (pr.state === 'OPEN') {
+                    const unresolvedCommentCount = await getUnresolvedCommentCount(workspacePath, pr.number);
+                    res.json({ ...pr, unresolvedCommentCount });
+                }
+                else {
+                    res.json({ ...pr, unresolvedCommentCount: 0 });
+                }
+            }
+            else {
+                res.status(404).json({ error: 'No PR found for branch' });
+            }
+        }
+        catch {
+            res.status(404).json({ error: 'No PR found for branch' });
+        }
+    });
+    // GET /workspaces/ci-status — CI check results for a workspace + branch
+    router.get('/ci-status', async (req, res) => {
+        const workspacePath = typeof req.query.path === 'string' ? req.query.path : undefined;
+        const branch = typeof req.query.branch === 'string' ? req.query.branch : undefined;
+        if (!workspacePath) {
+            res.status(400).json({ error: 'path query parameter is required' });
+            return;
+        }
+        try {
+            const status = await getCiStatus(workspacePath, branch ?? 'HEAD');
+            res.json(status);
+        }
+        catch {
+            res.json({ total: 0, passing: 0, failing: 0, pending: 0 });
+        }
+    });
+    // POST /workspaces/branch — switch branch for a workspace
+    router.post('/branch', async (req, res) => {
+        const workspacePath = typeof req.query.path === 'string' ? req.query.path : undefined;
+        if (!workspacePath) {
+            res.status(400).json({ error: 'path query parameter is required' });
+            return;
+        }
+        const body = req.body;
+        const branch = body.branch;
+        if (typeof branch !== 'string' || !branch) {
+            res.status(400).json({ error: 'branch is required in request body' });
+            return;
+        }
+        const result = await switchBranch(workspacePath, branch);
+        if (result.success) {
+            res.json({ path: workspacePath, branch });
+        }
+        else {
+            res.status(400).json({ error: result.error ?? `Failed to switch to branch: ${branch}` });
+        }
+    });
+    // POST /workspaces/worktree — create a new worktree with the next mountain name
+    router.post('/worktree', async (req, res) => {
+        const workspacePath = typeof req.query.path === 'string' ? req.query.path : undefined;
+        if (!workspacePath) {
+            res.status(400).json({ error: 'path query parameter is required' });
+            return;
+        }
+        const existingBranch = typeof req.body?.branch === 'string' ? req.body.branch : undefined;
+        const resolved = path.resolve(workspacePath);
+        const config = getConfig();
+        const settings = getWorkspaceSettings(config, resolved);
+        let branchName;
+        let mountainName;
+        let gitArgs;
+        let nextMountainIndex;
+        if (existingBranch) {
+            // Checkout existing branch into a worktree — sanitize branch name for use as directory name
+            mountainName = existingBranch.replace(/\//g, '-').replace(/[^a-zA-Z0-9._-]/g, '');
+            branchName = existingBranch;
+            gitArgs = ['worktree', 'add', path.join(resolved, '.worktrees', mountainName), existingBranch];
+        }
+        else {
+            // Create a new branch using the next mountain name
+            const index = settings.nextMountainIndex ?? 0;
+            mountainName = MOUNTAIN_NAMES[index % MOUNTAIN_NAMES.length] ?? 'everest';
+            branchName = (settings.branchPrefix ?? '') + mountainName;
+            nextMountainIndex = index + 1;
+            // Detect base branch: user setting > git detected > fallback
+            let baseBranch = settings.defaultBranch;
+            if (!baseBranch) {
+                const detected = await detectGitRepo(resolved);
+                baseBranch = detected.defaultBranch ?? 'main';
+            }
+            gitArgs = ['worktree', 'add', '-b', branchName, path.join(resolved, '.worktrees', mountainName), baseBranch];
+        }
+        const worktreePath = path.join(resolved, '.worktrees', mountainName);
+        try {
+            // Ensure .worktrees/ is in .gitignore
+            const gitignorePath = path.join(resolved, '.gitignore');
+            try {
+                const existing = await fs.promises.readFile(gitignorePath, 'utf8');
+                if (!existing.includes('.worktrees/')) {
+                    await fs.promises.appendFile(gitignorePath, '\n.worktrees/\n');
+                }
+            }
+            catch {
+                await fs.promises.writeFile(gitignorePath, '.worktrees/\n');
+            }
+            await exec('git', gitArgs, { cwd: resolved });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            res.status(500).json({ error: `Failed to create worktree: ${msg}` });
+            return;
+        }
+        // Increment mountain counter AFTER successful creation (don't skip names on failure)
+        if (nextMountainIndex !== undefined) {
+            setWorkspaceSettings(configPath, config, resolved, { nextMountainIndex });
+        }
+        res.json({ branchName, mountainName, worktreePath });
+    });
+    // GET /workspaces/current-branch — current checked-out branch for a path
+    router.get('/current-branch', async (req, res) => {
+        const workspacePath = typeof req.query.path === 'string' ? req.query.path : undefined;
+        if (!workspacePath) {
+            res.status(400).json({ error: 'path query parameter is required' });
+            return;
+        }
+        const branch = await getCurrentBranch(path.resolve(workspacePath));
+        res.json({ branch });
+    });
+    // GET /workspaces/browse — browse filesystem directories for tree UI
+    router.get('/browse', async (req, res) => {
+        const rawPath = typeof req.query.path === 'string' ? req.query.path : '~';
+        const prefix = typeof req.query.prefix === 'string' ? req.query.prefix : '';
+        const showHidden = req.query.showHidden === 'true';
+        // Resolve ~ to home directory
+        const expanded = rawPath === '~' || rawPath.startsWith('~/')
+            ? path.join(os.homedir(), rawPath.slice(1))
+            : rawPath;
+        const resolved = path.resolve(expanded);
+        let stat;
+        try {
+            stat = await fs.promises.stat(resolved);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === 'EACCES') {
+                res.status(403).json({ error: 'Permission denied' });
+            }
+            else {
+                res.status(400).json({ error: `Path does not exist: ${resolved}` });
+            }
+            return;
+        }
+        if (!stat.isDirectory()) {
+            res.status(400).json({ error: `Not a directory: ${resolved}` });
+            return;
+        }
+        let dirents;
+        try {
+            dirents = await fs.promises.readdir(resolved, { withFileTypes: true });
+        }
+        catch {
+            res.status(403).json({ error: 'Cannot read directory' });
+            return;
+        }
+        // Filter to directories only, apply denylist, hidden filter, prefix filter
+        let dirs = dirents.filter((d) => {
+            if (!d.isDirectory())
+                return false;
+            if (BROWSE_DENYLIST.has(d.name))
+                return false;
+            // Also check if name contains a path separator component in denylist
+            // e.g. "Library/Caches" — we check the full name, not path components
+            if (!showHidden && d.name.startsWith('.'))
+                return false;
+            if (prefix && !d.name.toLowerCase().startsWith(prefix.toLowerCase()))
+                return false;
+            return true;
+        });
+        dirs.sort((a, b) => a.name.toLowerCase().localeCompare(b.name.toLowerCase()));
+        const total = dirs.length;
+        const truncated = dirs.length > BROWSE_MAX_ENTRIES;
+        if (truncated)
+            dirs = dirs.slice(0, BROWSE_MAX_ENTRIES);
+        // Enrich each entry with isGitRepo and hasChildren (parallelized)
+        const entries = await Promise.all(dirs.map(async (d) => {
+            const entryPath = path.join(resolved, d.name);
+            let isGitRepo = false;
+            try {
+                const gitStat = await fs.promises.stat(path.join(entryPath, '.git'));
+                isGitRepo = gitStat.isDirectory();
+            }
+            catch {
+                // not a git repo
+            }
+            let hasChildren = false;
+            try {
+                const children = await fs.promises.readdir(entryPath, { withFileTypes: true });
+                hasChildren = children.some((c) => c.isDirectory() && !BROWSE_DENYLIST.has(c.name));
+            }
+            catch {
+                // can't read — treat as no children
+            }
+            return {
+                name: d.name,
+                path: entryPath,
+                isGitRepo,
+                hasChildren,
+            };
+        }));
+        res.json({ resolved, entries, truncated, total });
+    });
+    // GET /workspaces/autocomplete — path prefix autocomplete
+    router.get('/autocomplete', async (req, res) => {
+        const prefix = typeof req.query.prefix === 'string' ? req.query.prefix : '';
+        if (!prefix) {
+            res.json({ suggestions: [] });
+            return;
+        }
+        const expanded = prefix.startsWith('~')
+            ? path.join(process.env.HOME ?? '~', prefix.slice(1))
+            : prefix;
+        let dirToRead;
+        let partialName;
+        if (expanded.endsWith('/') || expanded.endsWith(path.sep)) {
+            // User typed a trailing slash — list immediate children of that dir
+            dirToRead = expanded;
+            partialName = '';
+        }
+        else {
+            dirToRead = path.dirname(expanded);
+            partialName = path.basename(expanded).toLowerCase();
+        }
+        let suggestions = [];
+        try {
+            const entries = await fs.promises.readdir(dirToRead, { withFileTypes: true });
+            suggestions = entries
+                .filter((e) => {
+                if (!e.isDirectory())
+                    return false;
+                if (e.name.startsWith('.'))
+                    return false;
+                if (!partialName)
+                    return true;
+                return e.name.toLowerCase().startsWith(partialName);
+            })
+                .map((e) => path.join(dirToRead, e.name))
+                .slice(0, 20); // cap results
+        }
+        catch {
+            // Directory doesn't exist or permission denied — return empty
+        }
+        res.json({ suggestions });
+    });
+    return router;
+}