@geminilight/mindos 0.6.72 → 0.6.73

package/_standalone/__tests__/api/mcp-install.test.ts

@@ -0,0 +1,400 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { NextRequest } from 'next/server';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+let tempHome: string;
+let origHome: string;
+
+beforeEach(() => {
+  tempHome = fs.mkdtempSync(path.join(os.tmpdir(), 'mindos-mcp-test-'));
+  origHome = process.env.HOME ?? '';
+  // Override HOME so expandHome('~/...') resolves to our temp dir
+  process.env.HOME = tempHome;
+});
+
+afterEach(() => {
+  process.env.HOME = origHome;
+  fs.rmSync(tempHome, { recursive: true, force: true });
+});
+
+async function importInstallRoute() {
+  return await import('../../app/api/mcp/install/route');
+}
+
+async function importAgentsRoute() {
+  return await import('../../app/api/mcp/agents/route');
+}
+
+describe('POST /api/mcp/install', () => {
+  it('returns error for unknown agent key', async () => {
+    const { POST } = await importInstallRoute();
+    const req = new NextRequest('http://localhost/api/mcp/install', {
+      method: 'POST',
+      body: JSON.stringify({
+        agents: [{ key: 'fake-agent', scope: 'global' }],
+        transport: 'stdio',
+      }),
+      headers: { 'content-type': 'application/json' },
+    });
+    const res = await POST(req);
+    const body = await res.json();
+    expect(body.results[0].status).toBe('error');
+    expect(body.results[0].message).toMatch(/Unknown agent/);
+  });
+
+  it('installs stdio entry to claude-code global config', async () => {
+    const { POST } = await importInstallRoute();
+    const req = new NextRequest('http://localhost/api/mcp/install', {
+      method: 'POST',
+      body: JSON.stringify({
+        agents: [{ key: 'claude-code', scope: 'global' }],
+        transport: 'stdio',
+      }),
+      headers: { 'content-type': 'application/json' },
+    });
+    const res = await POST(req);
+    const body = await res.json();
+    expect(body.results[0].status).toBe('ok');
+
+    // Verify config file was written
+    const configPath = path.join(tempHome, '.claude.json');
+    expect(fs.existsSync(configPath)).toBe(true);
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    expect(config.mcpServers.mindos).toBeDefined();
+    expect(config.mcpServers.mindos.type).toBe('stdio');
+    expect(config.mcpServers.mindos.command).toBe('mindos');
+  });
+
+  it('installs http entry with URL and token', async () => {
+    const { POST } = await importInstallRoute();
+    const req = new NextRequest('http://localhost/api/mcp/install', {
+      method: 'POST',
+      body: JSON.stringify({
+        agents: [{ key: 'claude-code', scope: 'global' }],
+        transport: 'http',
+        url: 'http://example.com/mcp',
+        token: 'secret123',
+      }),
+      headers: { 'content-type': 'application/json' },
+    });
+    const res = await POST(req);
+    const body = await res.json();
+    expect(body.results[0].status).toBe('ok');
+
+    const configPath = path.join(tempHome, '.claude.json');
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    expect(config.mcpServers.mindos.url).toBe('http://example.com/mcp');
+    expect(config.mcpServers.mindos.headers.Authorization).toBe('Bearer secret123');
+  });
+
+  it('preserves existing config entries when installing', async () => {
+    // Pre-seed a config file with another MCP server
+    const configPath = path.join(tempHome, '.claude.json');
+    fs.writeFileSync(configPath, JSON.stringify({
+      mcpServers: { 'other-server': { url: 'http://other.com/mcp' } },
+    }, null, 2), 'utf-8');
+
+    const { POST } = await importInstallRoute();
+    const req = new NextRequest('http://localhost/api/mcp/install', {
+      method: 'POST',
+      body: JSON.stringify({
+        agents: [{ key: 'claude-code', scope: 'global' }],
+        transport: 'stdio',
+      }),
+      headers: { 'content-type': 'application/json' },
+    });
+    await POST(req);
+
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    // Original server preserved
+    expect(config.mcpServers['other-server'].url).toBe('http://other.com/mcp');
+    // New server added
+    expect(config.mcpServers.mindos).toBeDefined();
+  });
+
+  it('returns error for agent without project scope', async () => {
+    const { POST } = await importInstallRoute();
+    const req = new NextRequest('http://localhost/api/mcp/install', {
+      method: 'POST',
+      body: JSON.stringify({
+        agents: [{ key: 'windsurf', scope: 'project' }],
+        transport: 'stdio',
+      }),
+      headers: { 'content-type': 'application/json' },
+    });
+    const res = await POST(req);
+    const body = await res.json();
+    expect(body.results[0].status).toBe('error');
+    expect(body.results[0].message).toMatch(/does not support/);
+  });
+
+  it('installs codex agent in TOML format', async () => {
+    const { POST } = await importInstallRoute();
+    const req = new NextRequest('http://localhost/api/mcp/install', {
+      method: 'POST',
+      body: JSON.stringify({
+        agents: [{ key: 'codex', scope: 'global' }],
+        transport: 'stdio',
+      }),
+      headers: { 'content-type': 'application/json' },
+    });
+    const res = await POST(req);
+    const body = await res.json();
+    expect(body.results[0].status).toBe('ok');
+
+    const configPath = path.join(tempHome, '.codex', 'config.toml');
+    expect(fs.existsSync(configPath)).toBe(true);
+    const content = fs.readFileSync(configPath, 'utf-8');
+    expect(content).toContain('[mcp_servers.mindos]');
+    expect(content).toContain('type = "stdio"');
+    expect(content).toContain('command = "mindos"');
+    expect(content).toContain('MCP_TRANSPORT = "stdio"');
+  });
+
+  it('preserves existing TOML content when installing codex', async () => {
+    const configDir = path.join(tempHome, '.codex');
+    fs.mkdirSync(configDir, { recursive: true });
+    const configPath = path.join(configDir, 'config.toml');
+    fs.writeFileSync(configPath, '[other_section]\nkey = "value"\n', 'utf-8');
+
+    const { POST } = await importInstallRoute();
+    const req = new NextRequest('http://localhost/api/mcp/install', {
+      method: 'POST',
+      body: JSON.stringify({
+        agents: [{ key: 'codex', scope: 'global' }],
+        transport: 'stdio',
+      }),
+      headers: { 'content-type': 'application/json' },
+    });
+    await POST(req);
+
+    const content = fs.readFileSync(configPath, 'utf-8');
+    expect(content).toContain('[other_section]');
+    expect(content).toContain('key = "value"');
+    expect(content).toContain('[mcp_servers.mindos]');
+  });
+
+  it('handles empty config file gracefully (e.g. fresh VS Code mcp.json)', async () => {
+    const { POST } = await importInstallRoute();
+    // Pre-create an empty config file (common with VS Code)
+    const copilotDir = path.join(tempHome, '.config', 'Code', 'User');
+    fs.mkdirSync(copilotDir, { recursive: true });
+    fs.writeFileSync(path.join(copilotDir, 'mcp.json'), '', 'utf-8');
+
+    const req = new NextRequest('http://localhost/api/mcp/install', {
+      method: 'POST',
+      body: JSON.stringify({
+        agents: [{ key: 'github-copilot', scope: 'global' }],
+        transport: 'stdio',
+      }),
+      headers: { 'content-type': 'application/json' },
+    });
+    const res = await POST(req);
+    const body = await res.json();
+    expect(body.results[0].status).toBe('ok');
+
+    const config = JSON.parse(fs.readFileSync(path.join(copilotDir, 'mcp.json'), 'utf-8'));
+    expect(config.servers.mindos.type).toBe('stdio');
+  });
+
+  it('installs github-copilot agent with servers key for global scope', async () => {
+    const { POST } = await importInstallRoute();
+    const req = new NextRequest('http://localhost/api/mcp/install', {
+      method: 'POST',
+      body: JSON.stringify({
+        agents: [{ key: 'github-copilot', scope: 'global' }],
+        transport: 'stdio',
+      }),
+      headers: { 'content-type': 'application/json' },
+    });
+    const res = await POST(req);
+    const body = await res.json();
+    expect(body.results[0].status).toBe('ok');
+
+    const configPath = body.results[0].path;
+    const absPath = configPath.replace('~', tempHome);
+    expect(fs.existsSync(absPath)).toBe(true);
+    const config = JSON.parse(fs.readFileSync(absPath, 'utf-8'));
+    // GitHub Copilot global uses standalone mcp.json with top-level 'servers'
+    expect(config.servers).toBeDefined();
+    expect(config.servers.mindos).toBeDefined();
+    expect(config.servers.mindos.type).toBe('stdio');
+  });
+
+  it('installs github-copilot project scope with servers key', async () => {
+    // Create the .vscode directory first
+    fs.mkdirSync(path.join(process.cwd(), '.vscode'), { recursive: true });
+
+    const { POST } = await importInstallRoute();
+    const req = new NextRequest('http://localhost/api/mcp/install', {
+      method: 'POST',
+      body: JSON.stringify({
+        agents: [{ key: 'github-copilot', scope: 'project' }],
+        transport: 'stdio',
+      }),
+      headers: { 'content-type': 'application/json' },
+    });
+    const res = await POST(req);
+    const body = await res.json();
+    expect(body.results[0].status).toBe('ok');
+
+    const absPath = path.join(process.cwd(), '.vscode', 'mcp.json');
+    if (fs.existsSync(absPath)) {
+      const config = JSON.parse(fs.readFileSync(absPath, 'utf-8'));
+      // Project scope uses flat key 'servers', not nested mcp.servers
+      expect(config.servers).toBeDefined();
+      expect(config.servers.mindos).toBeDefined();
+      expect(config.servers.mindos.type).toBe('stdio');
+      // Clean up
+      fs.rmSync(absPath);
+    }
+  });
+
+  it('installs copaw agent with nested mcp.clients structure', async () => {
+    const { POST } = await importInstallRoute();
+
+    // Pre-seed CoPaw config with existing data (like the user's example)
+    const copawDir = path.join(tempHome, '.copaw');
+    fs.mkdirSync(copawDir, { recursive: true });
+    fs.writeFileSync(path.join(copawDir, 'config.json'), JSON.stringify({
+      mcp: {
+        clients: {
+          tavily_search: {
+            name: 'tavily_mcp',
+            enabled: false,
+            transport: 'stdio',
+            command: 'npx',
+            args: ['-y', 'tavily-mcp@latest'],
+          },
+        },
+      },
+    }, null, 2), 'utf-8');
+
+    const req = new NextRequest('http://localhost/api/mcp/install', {
+      method: 'POST',
+      body: JSON.stringify({
+        agents: [{ key: 'copaw', scope: 'global' }],
+        transport: 'stdio',
+      }),
+      headers: { 'content-type': 'application/json' },
+    });
+    const res = await POST(req);
+    const body = await res.json();
+    expect(body.results[0].status).toBe('ok');
+
+    // Verify config uses nested mcp.clients structure
+    const configPath = path.join(copawDir, 'config.json');
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    // mindos should be under mcp.clients, NOT under a flat "mcp" key
+    expect(config.mcp).toBeDefined();
+    expect(config.mcp.clients).toBeDefined();
+    expect(config.mcp.clients.mindos).toBeDefined();
+    expect(config.mcp.clients.mindos.type).toBe('stdio');
+    expect(config.mcp.clients.mindos.command).toBe('mindos');
+    // Existing entry should be preserved
+    expect(config.mcp.clients.tavily_search).toBeDefined();
+    expect(config.mcp.clients.tavily_search.command).toBe('npx');
+  });
+});
+
+describe('GET /api/mcp/agents', () => {
+  it('returns all 25 agents (1 builtin + 24 registry)', async () => {
+    const { GET } = await importAgentsRoute();
+    const res = await GET();
+    const body = await res.json();
+    expect(body.agents).toHaveLength(25);
+    const keys = body.agents.map((a: { key: string }) => a.key);
+    expect(keys).toContain('mindos');
+    expect(keys).toContain('claude-code');
+    expect(keys).toContain('cursor');
+    expect(keys).toContain('codebuddy');
+    expect(keys).toContain('iflow-cli');
+    expect(keys).toContain('kimi-cli');
+    expect(keys).toContain('opencode');
+    expect(keys).toContain('pi');
+    expect(keys).toContain('augment');
+    expect(keys).toContain('qwen-code');
+    expect(keys).toContain('qoder');
+    expect(keys).toContain('trae-cn');
+    expect(keys).toContain('roo');
+    expect(keys).toContain('github-copilot');
+    expect(keys).toContain('codex');
+    expect(keys).toContain('antigravity');
+    expect(keys).toContain('qclaw');
+    expect(keys).toContain('workbuddy');
+    expect(keys).toContain('lingma');
+    expect(keys).toContain('copaw');
+  });
+
+  it('detects installed agent from config file', async () => {
+    // Pre-seed a claude-code config
+    const configPath = path.join(tempHome, '.claude.json');
+    fs.writeFileSync(configPath, JSON.stringify({
+      mcpServers: {
+        mindos: { type: 'stdio', command: 'mindos', args: ['mcp'] },
+        github: { url: 'https://api.githubcopilot.com/mcp' },
+      },
+    }), 'utf-8');
+    fs.mkdirSync(path.join(tempHome, '.claude', 'skills', 'mindos'), { recursive: true });
+    fs.mkdirSync(path.join(tempHome, '.claude', 'skills', 'project-wiki'), { recursive: true });
+
+    const { GET } = await importAgentsRoute();
+    const res = await GET();
+    const body = await res.json();
+    const claude = body.agents.find((a: { key: string }) => a.key === 'claude-code');
+    expect(claude.installed).toBe(true);
+    expect(claude.scope).toBe('global');
+    expect(claude.transport).toBe('stdio');
+    expect(claude.skillMode).toBeDefined();
+    expect(typeof claude.hiddenRootPresent).toBe('boolean');
+    expect(typeof claude.runtimeConversationSignal).toBe('boolean');
+    expect(typeof claude.runtimeUsageSignal).toBe('boolean');
+    expect(Array.isArray(claude.configuredMcpServers)).toBe(true);
+    expect(claude.configuredMcpServers).toContain('mindos');
+    expect(claude.configuredMcpServers).toContain('github');
+    expect(claude.configuredMcpServerCount).toBe(2);
+    expect(Array.isArray(claude.installedSkillNames)).toBe(true);
+    expect(claude.installedSkillNames).toContain('mindos');
+    expect(claude.installedSkillNames).toContain('project-wiki');
+    expect(claude.installedSkillCount).toBe(2);
+  });
+
+  it('reports not installed when no config exists', async () => {
+    const { GET } = await importAgentsRoute();
+    const res = await GET();
+    const body = await res.json();
+    const cursor = body.agents.find((a: { key: string }) => a.key === 'cursor');
+    expect(cursor.installed).toBe(false);
+  });
+
+  it('sorts agents: installed first, then detected, then not found', async () => {
+    // Pre-seed claude-code as installed
+    const configPath = path.join(tempHome, '.claude.json');
+    fs.writeFileSync(configPath, JSON.stringify({
+      mcpServers: { mindos: { type: 'stdio', command: 'mindos', args: ['mcp'] } },
+    }), 'utf-8');
+
+    const { GET } = await importAgentsRoute();
+    const res = await GET();
+    const body = await res.json();
+    const agents = body.agents as { key: string; installed: boolean; present: boolean }[];
+
+    // mindos is always first (builtin)
+    expect(agents[0].key).toBe('mindos');
+    expect(agents[0].installed).toBe(true);
+
+    // claude-code should be second (installed via config)
+    expect(agents[1].key).toBe('claude-code');
+    expect(agents[1].installed).toBe(true);
+
+    // Verify ordering invariant: after mindos, no non-installed agent appears before an installed one
+    for (let i = 2; i < agents.length; i++) {
+      const prev = agents[i - 1];
+      const curr = agents[i];
+      const rankOf = (a: typeof prev) => a.installed ? 0 : a.present ? 1 : 2;
+      expect(rankOf(prev)).toBeLessThanOrEqual(rankOf(curr));
+    }
+  });
+});

package/_standalone/__tests__/api/recent-files.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from 'vitest';
+import { seedFile } from '../setup';
+import { GET } from '@/app/api/recent-files/route';
+import { invalidateCache } from '@/lib/fs';
+import { NextRequest } from 'next/server';
+
+function makeRequest(limit?: string) {
+  const url = new URL('http://localhost/api/recent-files');
+  if (limit) url.searchParams.set('limit', limit);
+  return new NextRequest(url);
+}
+
+describe('GET /api/recent-files', () => {
+  it('returns empty when no files exist', async () => {
+    invalidateCache();
+    const res = await GET(makeRequest());
+    const json = await res.json();
+    expect(json).toEqual([]);
+  });
+
+  it('returns recently modified files sorted by mtime', async () => {
+    seedFile('old.md', 'old');
+    // small delay to ensure different mtime
+    await new Promise(r => setTimeout(r, 50));
+    seedFile('new.md', 'new');
+    invalidateCache();
+    const res = await GET(makeRequest());
+    const json: Array<{ path: string }> = await res.json();
+    expect(json.length).toBe(2);
+    // newest first
+    expect(json[0].path).toBe('new.md');
+  });
+
+  it('respects limit param', async () => {
+    seedFile('a.md', 'a');
+    seedFile('b.md', 'b');
+    seedFile('c.md', 'c');
+    invalidateCache();
+    const res = await GET(makeRequest('2'));
+    const json = await res.json();
+    expect(json.length).toBe(2);
+  });
+});

package/_standalone/__tests__/api/retry.test.ts

@@ -0,0 +1,49 @@
+import { describe, it, expect } from 'vitest';
+import { isTransientError } from '@/lib/agent/retry';
+
+describe('isTransientError', () => {
+  it('returns true for timeout errors', () => {
+    expect(isTransientError(new Error('Request timeout'))).toBe(true);
+    expect(isTransientError(new Error('connect ETIMEDOUT'))).toBe(true);
+    expect(isTransientError(new Error('operation timed out after 30s'))).toBe(true);
+  });
+
+  it('returns true for rate limit errors', () => {
+    expect(isTransientError(new Error('429 Too Many Requests'))).toBe(true);
+    expect(isTransientError(new Error('Rate limit exceeded'))).toBe(true);
+    expect(isTransientError(new Error('too many requests, please retry'))).toBe(true);
+  });
+
+  it('returns true for server errors (5xx)', () => {
+    expect(isTransientError(new Error('500 Internal Server Error'))).toBe(true);
+    expect(isTransientError(new Error('502 Bad Gateway'))).toBe(true);
+    expect(isTransientError(new Error('503 Service Unavailable'))).toBe(true);
+    expect(isTransientError(new Error('service unavailable'))).toBe(true);
+  });
+
+  it('returns true for connection errors', () => {
+    expect(isTransientError(new Error('read ECONNRESET'))).toBe(true);
+    expect(isTransientError(new Error('connect ECONNREFUSED'))).toBe(true);
+    expect(isTransientError(new Error('socket hang up'))).toBe(true);
+  });
+
+  it('returns true for overload errors', () => {
+    expect(isTransientError(new Error('API is overloaded'))).toBe(true);
+    expect(isTransientError(new Error('at capacity, please retry'))).toBe(true);
+  });
+
+  it('returns false for auth errors', () => {
+    expect(isTransientError(new Error('401 Unauthorized'))).toBe(false);
+    expect(isTransientError(new Error('Invalid API key'))).toBe(false);
+  });
+
+  it('returns false for bad request errors', () => {
+    expect(isTransientError(new Error('400 Bad Request'))).toBe(false);
+    expect(isTransientError(new Error('Invalid input'))).toBe(false);
+  });
+
+  it('returns false for content policy errors', () => {
+    expect(isTransientError(new Error('Content policy violation'))).toBe(false);
+    expect(isTransientError(new Error('This request has been blocked'))).toBe(false);
+  });
+});

package/_standalone/__tests__/api/search.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'vitest';
+import { NextRequest } from 'next/server';
+import { seedFile } from '../setup';
+import { GET } from '../../app/api/search/route';
+import { invalidateCache } from '../../lib/fs';
+
+describe('GET /api/search', () => {
+  it('returns empty array for empty query', async () => {
+    const req = new NextRequest('http://localhost/api/search?q=');
+    const res = await GET(req);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toEqual([]);
+  });
+
+  it('finds files matching query', async () => {
+    seedFile('doc.md', 'This document talks about machine learning in depth');
+    seedFile('other.md', 'Completely unrelated content about cooking');
+    invalidateCache();
+
+    const req = new NextRequest('http://localhost/api/search?q=machine+learning');
+    const res = await GET(req);
+    expect(res.status).toBe(200);
+    const results = await res.json();
+
+    expect(Array.isArray(results)).toBe(true);
+    // Should find at least the document about machine learning
+    if (results.length > 0) {
+      expect(results[0].path).toBe('doc.md');
+    }
+  });
+
+  it('returns results with expected shape', async () => {
+    seedFile('target.md', 'specific unique keyword xylophone');
+    invalidateCache();
+
+    const req = new NextRequest('http://localhost/api/search?q=xylophone');
+    const res = await GET(req);
+    const results = await res.json();
+
+    if (results.length > 0) {
+      const r = results[0];
+      expect(r).toHaveProperty('path');
+      expect(r).toHaveProperty('snippet');
+      expect(r).toHaveProperty('score');
+    }
+  });
+});

package/_standalone/__tests__/api/settings.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect, vi } from 'vitest';
+import { NextRequest } from 'next/server';
+import { GET, POST } from '../../app/api/settings/route';
+import { readSettings, writeSettings } from '../../lib/settings';
+
+// The settings module is already mocked via setup.ts
+
+describe('GET /api/settings', () => {
+  it('returns settings with expected shape', async () => {
+    const res = await GET();
+    expect(res.status).toBe(200);
+    const body = await res.json();
+
+    expect(body).toHaveProperty('ai');
+    expect(body.ai).toHaveProperty('activeProvider');
+    expect(body.ai).toHaveProperty('providers');
+    expect(Array.isArray(body.ai.providers)).toBe(true);
+    expect(body.ai.providers.length).toBeGreaterThanOrEqual(1);
+    const anthropic = body.ai.providers.find((p: any) => p.protocol === 'anthropic');
+    const openai = body.ai.providers.find((p: any) => p.protocol === 'openai');
+    expect(anthropic).toBeDefined();
+    expect(anthropic).toHaveProperty('apiKey');
+    expect(anthropic).toHaveProperty('model');
+    expect(openai).toBeDefined();
+    expect(openai).toHaveProperty('apiKey');
+    expect(openai).toHaveProperty('model');
+    expect(openai).toHaveProperty('baseUrl');
+    expect(body).toHaveProperty('mindRoot');
+    expect(body).toHaveProperty('envOverrides');
+    expect(body).toHaveProperty('envValues');
+  });
+});
+
+describe('POST /api/settings', () => {
+  it('calls writeSettings and returns ok', async () => {
+    const req = new NextRequest('http://localhost/api/settings', {
+      method: 'POST',
+      body: JSON.stringify({
+        ai: {
+          activeProvider: 'p_openai01',
+          providers: [
+            { id: 'p_openai01', name: 'OpenAI', protocol: 'openai', apiKey: 'sk-test', model: 'gpt-5.4', baseUrl: '' },
+          ],
+        },
+      }),
+      headers: { 'content-type': 'application/json' },
+    });
+
+    const res = await POST(req);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.ok).toBe(true);
+
+    expect(writeSettings).toHaveBeenCalled();
+  });
+});

package/_standalone/__tests__/api/setup-paths.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { NextRequest } from 'next/server';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+let fakeHome: string;
+
+beforeEach(() => {
+  fakeHome = fs.mkdtempSync(path.join(os.tmpdir(), 'mindos-setup-home-'));
+  fs.mkdirSync(path.join(fakeHome, 'Documents'), { recursive: true });
+  fs.mkdirSync(path.join(fakeHome, 'Projects'), { recursive: true });
+  fs.writeFileSync(path.join(fakeHome, '.hidden'), 'secret', 'utf-8');
+
+  vi.resetModules();
+  vi.doMock('node:os', async () => {
+    const actual = await vi.importActual<typeof import('node:os')>('node:os');
+    return {
+      ...actual,
+      homedir: () => fakeHome,
+    };
+  });
+});
+
+afterEach(() => {
+  vi.doUnmock('node:os');
+  vi.restoreAllMocks();
+  fs.rmSync(fakeHome, { recursive: true, force: true });
+});
+
+async function importCheckPathRoute() {
+  return await import('../../app/api/setup/check-path/route');
+}
+
+async function importLsRoute() {
+  return await import('../../app/api/setup/ls/route');
+}
+
+describe('setup path normalization', () => {
+  it('treats bare tilde as the home directory in check-path', async () => {
+    const { POST } = await importCheckPathRoute();
+    const req = new NextRequest('http://localhost/api/setup/check-path', {
+      method: 'POST',
+      body: JSON.stringify({ path: '~' }),
+      headers: { 'content-type': 'application/json' },
+    });
+
+    const res = await POST(req);
+    const body = await res.json();
+
+    expect(res.status).toBe(200);
+    expect(body.exists).toBe(true);
+    expect(body.empty).toBe(false);
+    expect(body.count).toBe(2);
+  });
+
+  it('keeps ls and check-path consistent for bare tilde', async () => {
+    const { POST: listDirs } = await importLsRoute();
+    const { POST: checkPath } = await importCheckPathRoute();
+
+    const lsReq = new NextRequest('http://localhost/api/setup/ls', {
+      method: 'POST',
+      body: JSON.stringify({ path: '~' }),
+      headers: { 'content-type': 'application/json' },
+    });
+    const checkReq = new NextRequest('http://localhost/api/setup/check-path', {
+      method: 'POST',
+      body: JSON.stringify({ path: '~' }),
+      headers: { 'content-type': 'application/json' },
+    });
+
+    const lsRes = await listDirs(lsReq);
+    const checkRes = await checkPath(checkReq);
+    const lsBody = await lsRes.json();
+    const checkBody = await checkRes.json();
+
+    expect(lsBody.dirs).toEqual(['Documents', 'Projects']);
+    expect(checkBody.exists).toBe(true);
+    expect(checkBody.count).toBe(lsBody.dirs.length);
+  });
+});