@dpesch/mantisbt-mcp-server 1.0.0

package/scripts/record-fixtures.ts

@@ -0,0 +1,138 @@
+import { writeFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { MantisClient } from '../src/client.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// ---------------------------------------------------------------------------
+// .env.local laden (falls vorhanden)
+// ---------------------------------------------------------------------------
+
+try {
+  const envPath = join(__dirname, '..', '.env.local');
+  const lines = readFileSync(envPath, 'utf-8').split('\n');
+  for (const line of lines) {
+    const match = line.match(/^([^#=\s][^=]*)=(.*)$/);
+    if (match) {
+      const key = match[1].trim();
+      const value = match[2].trim().replace(/^["']|["']$/g, '');
+      if (!process.env[key]) process.env[key] = value;
+    }
+  }
+} catch {
+  // .env.local nicht vorhanden – ENV-Vars direkt nutzen
+}
+
+// ---------------------------------------------------------------------------
+// Config aus ENV
+// ---------------------------------------------------------------------------
+
+const baseUrlRaw = process.env['MANTIS_BASE_URL'];
+const apiKey = process.env['MANTIS_API_KEY'];
+
+if (!baseUrlRaw || !apiKey) {
+  console.error('Error: MANTIS_BASE_URL and MANTIS_API_KEY environment variables must be set.');
+  process.exit(1);
+}
+
+const baseUrl = baseUrlRaw.replace(/\/$/, '');
+
+// ---------------------------------------------------------------------------
+// Fixtures-Verzeichnis
+// ---------------------------------------------------------------------------
+
+const fixturesDir = join(__dirname, '..', 'tests', 'fixtures', 'recorded');
+mkdirSync(fixturesDir, { recursive: true });
+
+function saveFixture(filename: string, data: unknown): void {
+  const filePath = join(fixturesDir, filename);
+  writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+  console.log(`Saved: ${filePath}`);
+}
+
+// ---------------------------------------------------------------------------
+// Client instanziieren
+// ---------------------------------------------------------------------------
+
+const client = new MantisClient(baseUrl, apiKey);
+
+// ---------------------------------------------------------------------------
+// Fixtures aufzeichnen
+// ---------------------------------------------------------------------------
+
+async function recordFixtures(): Promise<void> {
+  // GET projects
+  let firstProjectId: number | undefined;
+  let projectIdWithVersions: number | undefined;
+  try {
+    const projectsResult = await client.get<{ projects: Array<{ id: number; name: string; versions?: unknown[] }> }>('projects');
+    saveFixture('list_projects.json', projectsResult);
+    if (Array.isArray(projectsResult.projects) && projectsResult.projects.length > 0) {
+      firstProjectId = projectsResult.projects[0]?.id;
+      // Erstes Projekt mit nicht-leeren Versionen bevorzugen
+      projectIdWithVersions = projectsResult.projects.find(
+        (p) => Array.isArray(p.versions) && p.versions.length > 0,
+      )?.id ?? firstProjectId;
+    }
+  } catch (err) {
+    console.error('Failed to fetch projects:', err instanceof Error ? err.message : String(err));
+  }
+
+  // GET users/me
+  try {
+    const userResult = await client.get<unknown>('users/me');
+    saveFixture('get_current_user.json', userResult);
+  } catch (err) {
+    console.error('Failed to fetch users/me:', err instanceof Error ? err.message : String(err));
+  }
+
+  // GET issues?page=1&page_size=3
+  let firstIssueId: number | undefined;
+  try {
+    const issuesResult = await client.get<{ issues: Array<{ id: number }> }>('issues', {
+      page: 1,
+      page_size: 3,
+    });
+    saveFixture('list_issues.json', issuesResult);
+    if (Array.isArray(issuesResult.issues) && issuesResult.issues.length > 0) {
+      firstIssueId = issuesResult.issues[0]?.id;
+    }
+  } catch (err) {
+    console.error('Failed to fetch issues:', err instanceof Error ? err.message : String(err));
+  }
+
+  // GET issues/{id}
+  if (firstIssueId !== undefined) {
+    try {
+      const issueResult = await client.get<unknown>(`issues/${firstIssueId}`);
+      saveFixture('get_issue.json', issueResult);
+    } catch (err) {
+      console.error(`Failed to fetch issues/${firstIssueId}:`, err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  // GET projects/{id}/versions + categories
+  if (firstProjectId !== undefined) {
+    const versionProjectId = projectIdWithVersions ?? firstProjectId;
+    try {
+      const versionsResult = await client.get<unknown>(`projects/${versionProjectId}/versions`);
+      saveFixture('get_project_versions.json', versionsResult);
+    } catch (err) {
+      console.error(`Failed to fetch projects/${versionProjectId}/versions:`, err instanceof Error ? err.message : String(err));
+    }
+
+    try {
+      const projectResult = await client.get<{ projects: Array<{ categories?: unknown[] }> }>(`projects/${firstProjectId}`);
+      saveFixture('get_project_categories.json', { categories: projectResult.projects?.[0]?.categories ?? [] });
+    } catch (err) {
+      console.error(`Failed to fetch projects/${firstProjectId} (categories):`, err instanceof Error ? err.message : String(err));
+    }
+  }
+}
+
+recordFixtures().catch((err) => {
+  console.error('Unexpected error:', err);
+  process.exit(1);
+});

package/tests/cache.test.ts

@@ -0,0 +1,149 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// vi.mock must be at module top level — vitest hoists it automatically
+vi.mock('node:fs/promises');
+
+import { readFile, writeFile, unlink, mkdir } from 'node:fs/promises';
+import { MetadataCache, type CachedMetadata } from '../src/cache.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const CACHE_DIR = '/tmp/test-cache';
+const TTL = 3600; // 1 hour in seconds
+
+function makeCache(): MetadataCache {
+  return new MetadataCache(CACHE_DIR, TTL);
+}
+
+function makeSampleMetadata(): CachedMetadata {
+  return {
+    timestamp: Date.now(),
+    projects: [{ id: 1, name: 'Test Project' }],
+    byProject: {},
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Setup
+// ---------------------------------------------------------------------------
+
+beforeEach(() => {
+  vi.resetAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// isValid()
+// ---------------------------------------------------------------------------
+
+describe('MetadataCache – isValid()', () => {
+  it('returns false when file does not exist (readFile throws)', async () => {
+    vi.mocked(readFile).mockRejectedValue(new Error('ENOENT'));
+
+    const cache = makeCache();
+    await expect(cache.isValid()).resolves.toBe(false);
+  });
+
+  it('returns true when file is fresh (within TTL)', async () => {
+    const file = { timestamp: Date.now(), data: makeSampleMetadata() };
+    vi.mocked(readFile).mockResolvedValue(JSON.stringify(file) as any);
+
+    const cache = makeCache();
+    await expect(cache.isValid()).resolves.toBe(true);
+  });
+
+  it('returns false when file has expired (timestamp older than TTL)', async () => {
+    const expiredTimestamp = Date.now() - (TTL + 1) * 1000;
+    const file = { timestamp: expiredTimestamp, data: makeSampleMetadata() };
+    vi.mocked(readFile).mockResolvedValue(JSON.stringify(file) as any);
+
+    const cache = makeCache();
+    await expect(cache.isValid()).resolves.toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// load()
+// ---------------------------------------------------------------------------
+
+describe('MetadataCache – load()', () => {
+  it('returns null when file does not exist', async () => {
+    vi.mocked(readFile).mockRejectedValue(new Error('ENOENT'));
+
+    const cache = makeCache();
+    await expect(cache.load()).resolves.toBeNull();
+  });
+
+  it('returns CachedMetadata when file exists', async () => {
+    const metadata = makeSampleMetadata();
+    const file = { timestamp: Date.now(), data: metadata };
+    vi.mocked(readFile).mockResolvedValue(JSON.stringify(file) as any);
+
+    const cache = makeCache();
+    const result = await cache.load();
+    expect(result).toEqual(metadata);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// save()
+// ---------------------------------------------------------------------------
+
+describe('MetadataCache – save()', () => {
+  it('calls mkdir with recursive:true and writeFile with JSON content', async () => {
+    vi.mocked(mkdir).mockResolvedValue(undefined);
+    vi.mocked(writeFile).mockResolvedValue(undefined);
+
+    const cache = makeCache();
+    const metadata = makeSampleMetadata();
+    await cache.save(metadata);
+
+    expect(mkdir).toHaveBeenCalledWith(CACHE_DIR, { recursive: true });
+    expect(writeFile).toHaveBeenCalledOnce();
+
+    // Verify the written JSON contains our data
+    const writtenContent = vi.mocked(writeFile).mock.calls[0][1] as string;
+    const parsed = JSON.parse(writtenContent) as { timestamp: number; data: CachedMetadata };
+    expect(parsed.data).toEqual(metadata);
+  });
+
+  it('writes a timestamp to the cache file', async () => {
+    vi.mocked(mkdir).mockResolvedValue(undefined);
+    vi.mocked(writeFile).mockResolvedValue(undefined);
+
+    const before = Date.now();
+    const cache = makeCache();
+    await cache.save(makeSampleMetadata());
+    const after = Date.now();
+
+    const writtenContent = vi.mocked(writeFile).mock.calls[0][1] as string;
+    const parsed = JSON.parse(writtenContent) as { timestamp: number };
+    expect(parsed.timestamp).toBeGreaterThanOrEqual(before);
+    expect(parsed.timestamp).toBeLessThanOrEqual(after);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// invalidate()
+// ---------------------------------------------------------------------------
+
+describe('MetadataCache – invalidate()', () => {
+  it('calls unlink on the cache file', async () => {
+    vi.mocked(unlink).mockResolvedValue(undefined);
+
+    const cache = makeCache();
+    await cache.invalidate();
+
+    expect(unlink).toHaveBeenCalledOnce();
+    const calledPath = vi.mocked(unlink).mock.calls[0][0] as string;
+    expect(calledPath).toContain('metadata.json');
+  });
+
+  it('does not throw when file does not exist (unlink rejects)', async () => {
+    vi.mocked(unlink).mockRejectedValue(new Error('ENOENT'));
+
+    const cache = makeCache();
+    await expect(cache.invalidate()).resolves.toBeUndefined();
+  });
+});

package/tests/client.test.ts

@@ -0,0 +1,241 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { MantisClient, MantisApiError } from '../src/client.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeResponse(
+  status: number,
+  body: string,
+  headers: Record<string, string> = {},
+): Response {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    statusText: `Status ${status}`,
+    text: () => Promise.resolve(body),
+    headers: {
+      get: (key: string) => headers[key] ?? null,
+    },
+  } as unknown as Response;
+}
+
+// ---------------------------------------------------------------------------
+// Setup
+// ---------------------------------------------------------------------------
+
+beforeEach(() => {
+  vi.unstubAllGlobals();
+});
+
+// ---------------------------------------------------------------------------
+// URL building
+// ---------------------------------------------------------------------------
+
+describe('MantisClient – URL building', () => {
+  it('appends /api/rest/<path> to the base URL', () => {
+    const fetchMock = vi.fn().mockResolvedValue(makeResponse(200, '{}'));
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = new MantisClient('https://mantis.example.com', 'token123');
+    return client.get('issues/42').then(() => {
+      const calledUrl: string = fetchMock.mock.calls[0][0] as string;
+      expect(calledUrl).toBe('https://mantis.example.com/api/rest/issues/42');
+    });
+  });
+
+  it('strips trailing slash from base URL', () => {
+    const fetchMock = vi.fn().mockResolvedValue(makeResponse(200, '{}'));
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = new MantisClient('https://mantis.example.com/', 'token123');
+    return client.get('issues').then(() => {
+      const calledUrl: string = fetchMock.mock.calls[0][0] as string;
+      expect(calledUrl).toBe('https://mantis.example.com/api/rest/issues');
+    });
+  });
+
+  it('appends defined query parameters', () => {
+    const fetchMock = vi.fn().mockResolvedValue(makeResponse(200, '{}'));
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = new MantisClient('https://mantis.example.com', 'token123');
+    return client.get('issues', { page_size: 10, page: 1 }).then(() => {
+      const calledUrl: string = fetchMock.mock.calls[0][0] as string;
+      const url = new URL(calledUrl);
+      expect(url.searchParams.get('page_size')).toBe('10');
+      expect(url.searchParams.get('page')).toBe('1');
+    });
+  });
+
+  it('omits undefined query parameters', () => {
+    const fetchMock = vi.fn().mockResolvedValue(makeResponse(200, '{}'));
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = new MantisClient('https://mantis.example.com', 'token123');
+    return client.get('issues', { page_size: 10, filter_id: undefined }).then(() => {
+      const calledUrl: string = fetchMock.mock.calls[0][0] as string;
+      const url = new URL(calledUrl);
+      expect(url.searchParams.has('filter_id')).toBe(false);
+      expect(url.searchParams.get('page_size')).toBe('10');
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Request headers
+// ---------------------------------------------------------------------------
+
+describe('MantisClient – request headers', () => {
+  it('sends Authorization and Content-Type headers', () => {
+    const fetchMock = vi.fn().mockResolvedValue(makeResponse(200, '{}'));
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = new MantisClient('https://mantis.example.com', 'myApiKey');
+    return client.get('issues').then(() => {
+      const options = fetchMock.mock.calls[0][1] as RequestInit;
+      const headers = options.headers as Record<string, string>;
+      expect(headers['Authorization']).toBe('myApiKey');
+      expect(headers['Content-Type']).toBe('application/json');
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// handleResponse
+// ---------------------------------------------------------------------------
+
+describe('MantisClient – handleResponse', () => {
+  it('returns parsed JSON on 200', () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      makeResponse(200, JSON.stringify({ id: 42 })),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = new MantisClient('https://mantis.example.com', 'token');
+    return client.get<{ id: number }>('issues/42').then((result) => {
+      expect(result).toEqual({ id: 42 });
+    });
+  });
+
+  it('returns undefined on 204 No Content', () => {
+    const fetchMock = vi.fn().mockResolvedValue(makeResponse(204, ''));
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = new MantisClient('https://mantis.example.com', 'token');
+    return client.delete('issues/42').then((result) => {
+      expect(result).toBeUndefined();
+    });
+  });
+
+  it('throws MantisApiError with statusCode on 4xx', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      makeResponse(404, JSON.stringify({ message: 'Issue not found' })),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = new MantisClient('https://mantis.example.com', 'token');
+    await expect(client.get('issues/9999')).rejects.toMatchObject({
+      statusCode: 404,
+      name: 'MantisApiError',
+    });
+  });
+
+  it('uses raw body as message when JSON has no message field', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      makeResponse(403, JSON.stringify({ detail: 'forbidden' })),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = new MantisClient('https://mantis.example.com', 'token');
+    // When body is JSON but has no `message` key, the raw body string is used
+    await expect(client.get('issues')).rejects.toThrow('{"detail":"forbidden"}');
+  });
+
+  it('MantisApiError is instanceof Error', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      makeResponse(401, JSON.stringify({ message: 'Unauthorized' })),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = new MantisClient('https://mantis.example.com', 'token');
+    await expect(client.get('issues')).rejects.toBeInstanceOf(MantisApiError);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// HTTP methods
+// ---------------------------------------------------------------------------
+
+describe('MantisClient – HTTP methods', () => {
+  it('sends POST with JSON body', () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      makeResponse(201, JSON.stringify({ id: 1 })),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = new MantisClient('https://mantis.example.com', 'token');
+    const payload = { summary: 'New issue', project: { id: 1 } };
+    return client.post('issues', payload).then(() => {
+      const options = fetchMock.mock.calls[0][1] as RequestInit;
+      expect(options.method).toBe('POST');
+      expect(options.body).toBe(JSON.stringify(payload));
+    });
+  });
+
+  it('sends PATCH request', () => {
+    const fetchMock = vi.fn().mockResolvedValue(
+      makeResponse(200, JSON.stringify({ id: 1 })),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = new MantisClient('https://mantis.example.com', 'token');
+    return client.patch('issues/1', { summary: 'Updated' }).then(() => {
+      const options = fetchMock.mock.calls[0][1] as RequestInit;
+      expect(options.method).toBe('PATCH');
+    });
+  });
+
+  it('sends DELETE request', () => {
+    const fetchMock = vi.fn().mockResolvedValue(makeResponse(204, ''));
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = new MantisClient('https://mantis.example.com', 'token');
+    return client.delete('issues/1').then(() => {
+      const options = fetchMock.mock.calls[0][1] as RequestInit;
+      expect(options.method).toBe('DELETE');
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// responseObserver
+// ---------------------------------------------------------------------------
+
+describe('MantisClient – responseObserver', () => {
+  it('calls responseObserver on successful response', () => {
+    const observer = vi.fn();
+    const fakeResponse = makeResponse(200, '{}');
+    const fetchMock = vi.fn().mockResolvedValue(fakeResponse);
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = new MantisClient('https://mantis.example.com', 'token', observer);
+    return client.get('issues').then(() => {
+      expect(observer).toHaveBeenCalledOnce();
+      expect(observer).toHaveBeenCalledWith(fakeResponse);
+    });
+  });
+
+  it('does not call responseObserver on error response', async () => {
+    const observer = vi.fn();
+    const fetchMock = vi.fn().mockResolvedValue(
+      makeResponse(500, JSON.stringify({ message: 'Internal Server Error' })),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const client = new MantisClient('https://mantis.example.com', 'token', observer);
+    await expect(client.get('issues')).rejects.toBeInstanceOf(MantisApiError);
+    expect(observer).not.toHaveBeenCalled();
+  });
+});

package/tests/config.test.ts

@@ -0,0 +1,164 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// vi.mock is hoisted — must be at module top level
+vi.mock('node:fs/promises');
+
+import { readFile } from 'node:fs/promises';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Reset the module registry so that the `cachedConfig` singleton in config.ts
+ * is re-initialized for each test. Then import getConfig fresh.
+ */
+async function freshGetConfig(): Promise<(typeof import('../src/config.js'))['getConfig']> {
+  vi.resetModules();
+  const mod = await import('../src/config.js');
+  return mod.getConfig;
+}
+
+// ---------------------------------------------------------------------------
+// Setup
+// ---------------------------------------------------------------------------
+
+beforeEach(() => {
+  vi.resetAllMocks();
+  vi.unstubAllEnvs();
+});
+
+// ---------------------------------------------------------------------------
+// ENV-based configuration
+// ---------------------------------------------------------------------------
+
+describe('getConfig() – ENV variables', () => {
+  it('reads baseUrl and apiKey from environment variables', async () => {
+    vi.stubEnv('MANTIS_BASE_URL', 'https://mantis.example.com/api/rest');
+    vi.stubEnv('MANTIS_API_KEY', 'env-api-key');
+
+    const getConfig = await freshGetConfig();
+    const config = await getConfig();
+
+    expect(config.baseUrl).toBe('https://mantis.example.com/api/rest');
+    expect(config.apiKey).toBe('env-api-key');
+  });
+
+  it('strips trailing slash from baseUrl', async () => {
+    vi.stubEnv('MANTIS_BASE_URL', 'https://mantis.example.com/api/rest/');
+    vi.stubEnv('MANTIS_API_KEY', 'key');
+
+    const getConfig = await freshGetConfig();
+    const config = await getConfig();
+
+    expect(config.baseUrl).toBe('https://mantis.example.com/api/rest');
+  });
+
+  it('parses MANTIS_CACHE_TTL as a number', async () => {
+    vi.stubEnv('MANTIS_BASE_URL', 'https://mantis.example.com');
+    vi.stubEnv('MANTIS_API_KEY', 'key');
+    vi.stubEnv('MANTIS_CACHE_TTL', '7200');
+
+    const getConfig = await freshGetConfig();
+    const config = await getConfig();
+
+    expect(config.cacheTtl).toBe(7200);
+  });
+
+  it('uses 3600 as default cacheTtl when MANTIS_CACHE_TTL is not set', async () => {
+    vi.stubEnv('MANTIS_BASE_URL', 'https://mantis.example.com');
+    vi.stubEnv('MANTIS_API_KEY', 'key');
+
+    const getConfig = await freshGetConfig();
+    const config = await getConfig();
+
+    expect(config.cacheTtl).toBe(3600);
+  });
+
+  it('uses MANTIS_CACHE_DIR when provided', async () => {
+    vi.stubEnv('MANTIS_BASE_URL', 'https://mantis.example.com');
+    vi.stubEnv('MANTIS_API_KEY', 'key');
+    vi.stubEnv('MANTIS_CACHE_DIR', '/custom/cache/dir');
+
+    const getConfig = await freshGetConfig();
+    const config = await getConfig();
+
+    expect(config.cacheDir).toBe('/custom/cache/dir');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// JSON fallback
+// ---------------------------------------------------------------------------
+
+describe('getConfig() – mantis.json fallback', () => {
+  it('falls back to ~/.claude/mantis.json when ENV vars are missing', async () => {
+    const json = JSON.stringify({ base_url: 'https://from-json.example.com', api_key: 'json-key' });
+    vi.mocked(readFile).mockResolvedValue(json as any);
+
+    const getConfig = await freshGetConfig();
+    const config = await getConfig();
+
+    expect(config.baseUrl).toBe('https://from-json.example.com');
+    expect(config.apiKey).toBe('json-key');
+  });
+
+  it('prefers ENV vars over mantis.json values', async () => {
+    vi.stubEnv('MANTIS_BASE_URL', 'https://from-env.example.com');
+    vi.stubEnv('MANTIS_API_KEY', 'env-key');
+    const json = JSON.stringify({ base_url: 'https://from-json.example.com', api_key: 'json-key' });
+    vi.mocked(readFile).mockResolvedValue(json as any);
+
+    const getConfig = await freshGetConfig();
+    const config = await getConfig();
+
+    expect(config.baseUrl).toBe('https://from-env.example.com');
+    expect(config.apiKey).toBe('env-key');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Error cases
+// ---------------------------------------------------------------------------
+
+describe('getConfig() – errors', () => {
+  it('throws when neither ENV nor mantis.json provides baseUrl', async () => {
+    vi.stubEnv('MANTIS_API_KEY', 'some-key');
+    vi.mocked(readFile).mockRejectedValue(new Error('ENOENT'));
+
+    const getConfig = await freshGetConfig();
+    await expect(getConfig()).rejects.toThrow('MANTIS_BASE_URL');
+  });
+
+  it('throws when neither ENV nor mantis.json provides apiKey', async () => {
+    vi.stubEnv('MANTIS_BASE_URL', 'https://mantis.example.com');
+    vi.mocked(readFile).mockRejectedValue(new Error('ENOENT'));
+
+    const getConfig = await freshGetConfig();
+    await expect(getConfig()).rejects.toThrow('MANTIS_API_KEY');
+  });
+
+  it('throws when no configuration is available at all', async () => {
+    vi.mocked(readFile).mockRejectedValue(new Error('ENOENT'));
+
+    const getConfig = await freshGetConfig();
+    await expect(getConfig()).rejects.toThrow('Missing required MantisBT configuration');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Singleton caching
+// ---------------------------------------------------------------------------
+
+describe('getConfig() – singleton', () => {
+  it('returns the same object on repeated calls within the same module instance', async () => {
+    vi.stubEnv('MANTIS_BASE_URL', 'https://mantis.example.com');
+    vi.stubEnv('MANTIS_API_KEY', 'key');
+
+    const getConfig = await freshGetConfig();
+    const first = await getConfig();
+    const second = await getConfig();
+
+    expect(first).toBe(second);
+  });
+});