@atlassian-dc-mcp/common 0.16.0 → 0.17.1

package/src/config/__tests__/registry.test.ts

@@ -0,0 +1,118 @@
+import { DefaultConfigRegistry } from '../registry.js';
+import type {
+  ConfigKey,
+  ProductDefinition,
+  ReadableSource,
+  SourceId,
+  WritableSource,
+} from '../source.js';
+
+const PRODUCT: ProductDefinition = {
+  id: 'jira',
+  envVars: {
+    host: 'JIRA_HOST',
+    apiBasePath: 'JIRA_API_BASE_PATH',
+    token: 'JIRA_API_TOKEN',
+    defaultPageSize: 'JIRA_DEFAULT_PAGE_SIZE',
+  },
+};
+
+class ReadOnlySource implements ReadableSource {
+  constructor(
+    public readonly id: SourceId,
+    public readonly priority: number,
+    public readonly values: Partial<Record<ConfigKey, string>> = {},
+  ) {}
+  read(_p: ProductDefinition, key: ConfigKey): string | undefined {
+    return this.values[key];
+  }
+  describe(): string {
+    return this.id;
+  }
+}
+
+class FakeWritableSource implements WritableSource {
+  calls: string[] = [];
+  available = true;
+  constructor(
+    public readonly id: SourceId,
+    public readonly priority: number,
+  ) {}
+  read(): string | undefined {
+    return undefined;
+  }
+  describe(): string {
+    return this.id;
+  }
+  isAvailable(): boolean {
+    return this.available;
+  }
+  write(_p: ProductDefinition, key: ConfigKey, value: string): void {
+    this.calls.push(`write:${key}:${value}`);
+  }
+  clear(_p: ProductDefinition, key: ConfigKey): void {
+    this.calls.push(`clear:${key}`);
+  }
+}
+
+describe('DefaultConfigRegistry', () => {
+  it('sorts sources by priority descending', () => {
+    const a = new ReadOnlySource('home-file', 60);
+    const b = new ReadOnlySource('process-env', 100);
+    const c = new ReadOnlySource('env-file', 80);
+    const registry = new DefaultConfigRegistry([a, b, c]);
+    expect(registry.sources.map((s) => s.id)).toEqual(['process-env', 'env-file', 'home-file']);
+  });
+
+  it('resolve returns the first non-empty value in priority order', () => {
+    const envFile = new ReadOnlySource('env-file', 80, { token: 'file-token' });
+    const processEnv = new ReadOnlySource('process-env', 100, { token: 'env-token' });
+    const registry = new DefaultConfigRegistry([envFile, processEnv]);
+    const resolved = registry.resolve(PRODUCT, 'token');
+    expect(resolved.value).toBe('env-token');
+    expect(resolved.from?.sourceId).toBe('process-env');
+  });
+
+  it('resolve falls through when a higher-priority source is empty', () => {
+    const envFile = new ReadOnlySource('env-file', 80, { token: 'file-token' });
+    const processEnv = new ReadOnlySource('process-env', 100, {});
+    const registry = new DefaultConfigRegistry([envFile, processEnv]);
+    expect(registry.resolve(PRODUCT, 'token').value).toBe('file-token');
+  });
+
+  it('locate returns all sources with values, priority order', () => {
+    const home = new ReadOnlySource('home-file', 60, { token: 'home-token' });
+    const env = new ReadOnlySource('process-env', 100, { token: 'env-token' });
+    const envFile = new ReadOnlySource('env-file', 80, {});
+    const registry = new DefaultConfigRegistry([home, env, envFile]);
+    const locs = registry.locate(PRODUCT, 'token');
+    expect(locs.map((l) => l.sourceId)).toEqual(['process-env', 'home-file']);
+  });
+
+  it('getWritableSource returns the first source matching the predicate', () => {
+    const a = new FakeWritableSource('home-file', 60);
+    const b = new FakeWritableSource('macos-keychain', 40);
+    const registry = new DefaultConfigRegistry([a, b]);
+    const found = registry.getWritableSource(
+      (s): s is FakeWritableSource => s instanceof FakeWritableSource && s.id === 'macos-keychain',
+    );
+    expect(found).toBe(b);
+  });
+
+  it('calls initialize on all sources when registry.initialize runs', () => {
+    const calls: string[] = [];
+    const makeSource = (id: SourceId, priority: number) =>
+      ({
+        id,
+        priority,
+        read: () => undefined,
+        describe: () => id,
+        initialize: (opts?: { cwd?: string }) => {
+          calls.push(`${id}:${opts?.cwd ?? ''}`);
+        },
+      }) satisfies ReadableSource;
+    const registry = new DefaultConfigRegistry([makeSource('env-file', 80), makeSource('process-env', 100)]);
+    registry.initialize({ cwd: '/tmp' });
+    expect(calls.sort()).toEqual(['env-file:/tmp', 'process-env:/tmp']);
+  });
+});

package/src/config/__tests__/resolve-base.test.ts

@@ -0,0 +1,101 @@
+import { resolveOpenApiBase } from '../resolve-base.js';
+
+describe('resolveOpenApiBase', () => {
+  it('combines bare host with default base path', () => {
+    const base = resolveOpenApiBase({
+      host: 'jira.example.com',
+      defaultBasePath: '/rest',
+    });
+    expect(base).toBe('https://jira.example.com/rest');
+  });
+
+  it('uses an explicit apiBasePath when it is a path', () => {
+    const base = resolveOpenApiBase({
+      host: 'jira.example.com',
+      apiBasePath: '/custom',
+      defaultBasePath: '/rest',
+    });
+    expect(base).toBe('https://jira.example.com/custom');
+  });
+
+  it('uses an empty default for confluence-style generated paths', () => {
+    const base = resolveOpenApiBase({
+      host: 'wiki.example.com',
+      defaultBasePath: '',
+    });
+    expect(base).toBe('https://wiki.example.com');
+  });
+
+  it('accepts a fully-qualified apiBasePath as a full URL override', () => {
+    const base = resolveOpenApiBase({
+      host: 'ignored.example.com',
+      apiBasePath: 'https://real.example.com/rest',
+      defaultBasePath: '/rest',
+    });
+    expect(base).toBe('https://real.example.com/rest');
+  });
+
+  it('strips known generated suffix from a fully-qualified apiBasePath', () => {
+    const base = resolveOpenApiBase({
+      host: 'ignored.example.com',
+      apiBasePath: 'https://real.example.com/rest/api/2',
+      defaultBasePath: '/rest',
+      strippableSuffixes: ['/api/2'],
+    });
+    expect(base).toBe('https://real.example.com/rest');
+  });
+
+  it('strips a confluence generated suffix from a fully-qualified apiBasePath with a context path', () => {
+    const base = resolveOpenApiBase({
+      host: 'ignored.example.com',
+      apiBasePath: 'https://wiki.example.com/confluence/rest/api',
+      defaultBasePath: '',
+      strippableSuffixes: ['/rest/api', '/rest'],
+    });
+    expect(base).toBe('https://wiki.example.com/confluence');
+  });
+
+  it('strips known generated suffix included by mistake (jira)', () => {
+    const base = resolveOpenApiBase({
+      host: 'jira.example.com',
+      apiBasePath: '/rest/api/2',
+      defaultBasePath: '/rest',
+      strippableSuffixes: ['/api/2'],
+    });
+    expect(base).toBe('https://jira.example.com/rest');
+  });
+
+  it('strips known generated suffix included by mistake (bitbucket)', () => {
+    const base = resolveOpenApiBase({
+      host: 'bb.example.com',
+      apiBasePath: '/rest/api/1.0',
+      defaultBasePath: '/rest',
+      strippableSuffixes: ['/api/1.0', '/api/latest'],
+    });
+    expect(base).toBe('https://bb.example.com/rest');
+  });
+
+  it('strips known generated suffix included by mistake (confluence)', () => {
+    const base = resolveOpenApiBase({
+      host: 'wiki.example.com',
+      apiBasePath: '/rest/api',
+      defaultBasePath: '',
+      strippableSuffixes: ['/rest/api', '/rest'],
+    });
+    expect(base).toBe('https://wiki.example.com');
+  });
+
+  it('preserves a host that already includes a scheme', () => {
+    const base = resolveOpenApiBase({
+      host: 'https://jira.example.com/',
+      defaultBasePath: '/rest',
+    });
+    expect(base).toBe('https://jira.example.com/rest');
+  });
+
+  it('throws when host and apiBasePath are both missing', () => {
+    expect(() =>
+      resolveOpenApiBase({ defaultBasePath: '/rest' }),
+    ).toThrow('host or apiBasePath must be provided');
+  });
+});

package/src/config/__tests__/sources/env-file.test.ts

@@ -0,0 +1,113 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { EnvFileSource, ATLASSIAN_DC_MCP_CONFIG_FILE_ENV_VAR } from '../../sources/env-file.js';
+import type { ProductDefinition } from '../../source.js';
+
+const JIRA: ProductDefinition = {
+  id: 'jira',
+  envVars: {
+    host: 'JIRA_HOST',
+    apiBasePath: 'JIRA_API_BASE_PATH',
+    token: 'JIRA_API_TOKEN',
+    defaultPageSize: 'JIRA_DEFAULT_PAGE_SIZE',
+  },
+};
+
+const BITBUCKET: ProductDefinition = {
+  id: 'bitbucket',
+  envVars: {
+    host: 'BITBUCKET_HOST',
+    apiBasePath: 'BITBUCKET_API_BASE_PATH',
+    token: 'BITBUCKET_API_TOKEN',
+    defaultPageSize: 'BITBUCKET_DEFAULT_PAGE_SIZE',
+  },
+};
+
+describe('EnvFileSource', () => {
+  const originalEnv = process.env;
+  let tempDir: string;
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+    delete process.env[ATLASSIAN_DC_MCP_CONFIG_FILE_ENV_VAR];
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'env-file-src-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  afterAll(() => {
+    process.env = originalEnv;
+  });
+
+  it('reads an explicit shared config file', () => {
+    const filePath = path.join(tempDir, 'shared.env');
+    fs.writeFileSync(filePath, 'JIRA_HOST=file-host\nJIRA_API_TOKEN=file-token\n');
+    process.env[ATLASSIAN_DC_MCP_CONFIG_FILE_ENV_VAR] = filePath;
+    const source = new EnvFileSource();
+    source.initialize({ cwd: tempDir });
+    expect(source.read(JIRA, 'host')).toBe('file-host');
+    expect(source.read(JIRA, 'token')).toBe('file-token');
+  });
+
+  it('reads cwd/.env when no explicit file is configured', () => {
+    fs.writeFileSync(path.join(tempDir, '.env'), 'BITBUCKET_HOST=cwd-host\n');
+    const source = new EnvFileSource();
+    source.initialize({ cwd: tempDir });
+    expect(source.read(BITBUCKET, 'host')).toBe('cwd-host');
+  });
+
+  it('throws when explicit file is relative', () => {
+    process.env[ATLASSIAN_DC_MCP_CONFIG_FILE_ENV_VAR] = 'relative/shared.env';
+    const source = new EnvFileSource();
+    expect(() => source.initialize({ cwd: tempDir })).toThrow(/must be an absolute path/);
+  });
+
+  it('throws when explicit file is missing', () => {
+    const missing = path.join(tempDir, 'missing.env');
+    process.env[ATLASSIAN_DC_MCP_CONFIG_FILE_ENV_VAR] = missing;
+    const source = new EnvFileSource();
+    expect(() => source.initialize({ cwd: tempDir })).toThrow(
+      `${ATLASSIAN_DC_MCP_CONFIG_FILE_ENV_VAR} points to a missing file: ${missing}`,
+    );
+  });
+
+  it('revalidates cache when mtime changes', () => {
+    const filePath = path.join(tempDir, 'shared.env');
+    fs.writeFileSync(filePath, 'JIRA_API_TOKEN=token-a\n');
+    const initial = new Date('2026-01-01T00:00:00.000Z');
+    fs.utimesSync(filePath, initial, initial);
+    process.env[ATLASSIAN_DC_MCP_CONFIG_FILE_ENV_VAR] = filePath;
+
+    const source = new EnvFileSource();
+    source.initialize({ cwd: tempDir });
+    expect(source.read(JIRA, 'token')).toBe('token-a');
+
+    fs.writeFileSync(filePath, 'JIRA_API_TOKEN=token-b\n');
+    const updated = new Date('2026-01-01T00:00:01.000Z');
+    fs.utimesSync(filePath, updated, updated);
+    expect(source.read(JIRA, 'token')).toBe('token-b');
+  });
+
+  it('returns empty object when cwd/.env is missing', () => {
+    const source = new EnvFileSource();
+    source.initialize({ cwd: tempDir });
+    expect(source.read(JIRA, 'host')).toBeUndefined();
+  });
+
+  it('evicts cache when an explicit file disappears after a successful read', () => {
+    const filePath = path.join(tempDir, 'shared.env');
+    fs.writeFileSync(filePath, 'JIRA_API_TOKEN=token-a\n');
+    process.env[ATLASSIAN_DC_MCP_CONFIG_FILE_ENV_VAR] = filePath;
+    const source = new EnvFileSource();
+    source.initialize({ cwd: tempDir });
+    expect(source.read(JIRA, 'token')).toBe('token-a');
+
+    fs.unlinkSync(filePath);
+    expect(() => source.read(JIRA, 'token')).toThrow(
+      `${ATLASSIAN_DC_MCP_CONFIG_FILE_ENV_VAR} points to a missing file: ${filePath}`,
+    );
+  });
+});

package/src/config/__tests__/sources/home-file.test.ts

@@ -0,0 +1,129 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { HomeFileSource, getHomeFilePath, HOME_DIR_NAME } from '../../sources/home-file.js';
+import type { ProductDefinition } from '../../source.js';
+
+const JIRA: ProductDefinition = {
+  id: 'jira',
+  envVars: {
+    host: 'JIRA_HOST',
+    apiBasePath: 'JIRA_API_BASE_PATH',
+    token: 'JIRA_API_TOKEN',
+    defaultPageSize: 'JIRA_DEFAULT_PAGE_SIZE',
+  },
+};
+
+const CONFLUENCE: ProductDefinition = {
+  id: 'confluence',
+  envVars: {
+    host: 'CONFLUENCE_HOST',
+    apiBasePath: 'CONFLUENCE_API_BASE_PATH',
+    token: 'CONFLUENCE_API_TOKEN',
+    defaultPageSize: 'CONFLUENCE_DEFAULT_PAGE_SIZE',
+  },
+};
+
+describe('HomeFileSource', () => {
+  let tempHome: string;
+  let homedirSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    tempHome = fs.mkdtempSync(path.join(os.tmpdir(), 'home-file-src-'));
+    homedirSpy = jest.spyOn(os, 'homedir').mockReturnValue(tempHome);
+  });
+
+  afterEach(() => {
+    homedirSpy.mockRestore();
+    fs.rmSync(tempHome, { recursive: true, force: true });
+  });
+
+  it('returns undefined when the home file does not exist', () => {
+    expect(new HomeFileSource().read(JIRA, 'host')).toBeUndefined();
+  });
+
+  it('writes values and reads them back', () => {
+    const source = new HomeFileSource();
+    source.write(JIRA, 'host', 'j-host');
+    source.write(JIRA, 'token', 'j-token');
+    expect(source.read(JIRA, 'host')).toBe('j-host');
+    expect(source.read(JIRA, 'token')).toBe('j-token');
+  });
+
+  it('writes files with mode 0600 on POSIX', () => {
+    if (process.platform === 'win32') {
+      return;
+    }
+    const source = new HomeFileSource();
+    source.write(JIRA, 'host', 'j-host');
+    const stat = fs.statSync(getHomeFilePath(JIRA));
+    expect(stat.mode & 0o777).toBe(0o600);
+  });
+
+  it('merge preserves unrelated keys', () => {
+    const filePath = getHomeFilePath(JIRA);
+    fs.mkdirSync(path.join(tempHome, HOME_DIR_NAME), { recursive: true });
+    fs.writeFileSync(filePath, 'JIRA_HOST=old\nUNRELATED_KEY=keep-me\n', { mode: 0o600 });
+    const source = new HomeFileSource();
+    source.write(JIRA, 'host', 'new');
+    const contents = fs.readFileSync(filePath, 'utf8');
+    expect(contents).toContain('JIRA_HOST=new');
+    expect(contents).toContain('UNRELATED_KEY=keep-me');
+  });
+
+  it('clear removes only the specified key', () => {
+    const source = new HomeFileSource();
+    source.write(JIRA, 'host', 'j-host');
+    source.write(JIRA, 'token', 'j-token');
+    source.clear(JIRA, 'token');
+    expect(source.read(JIRA, 'host')).toBe('j-host');
+    expect(source.read(JIRA, 'token')).toBeUndefined();
+  });
+
+  it('quotes values that contain whitespace', () => {
+    const source = new HomeFileSource();
+    source.write(JIRA, 'host', 'value with spaces');
+    const contents = fs.readFileSync(getHomeFilePath(JIRA), 'utf8');
+    expect(contents).toMatch(/JIRA_HOST="value with spaces"/);
+    expect(source.read(JIRA, 'host')).toBe('value with spaces');
+  });
+
+  it('stores each product in its own file', () => {
+    const source = new HomeFileSource();
+    source.write(JIRA, 'host', 'j-host');
+    source.write(CONFLUENCE, 'host', 'c-host');
+    expect(fs.existsSync(getHomeFilePath(JIRA))).toBe(true);
+    expect(fs.existsSync(getHomeFilePath(CONFLUENCE))).toBe(true);
+    expect(source.read(JIRA, 'host')).toBe('j-host');
+    expect(source.read(CONFLUENCE, 'host')).toBe('c-host');
+  });
+
+  it('evicts cache when the home file is deleted externally so writes do not merge stale values', () => {
+    const source = new HomeFileSource();
+    source.write(JIRA, 'host', 'stale-host');
+    expect(source.read(JIRA, 'host')).toBe('stale-host');
+
+    fs.unlinkSync(getHomeFilePath(JIRA));
+    expect(source.read(JIRA, 'host')).toBeUndefined();
+
+    source.write(JIRA, 'token', 'fresh-token');
+    const contents = fs.readFileSync(getHomeFilePath(JIRA), 'utf8');
+    expect(contents).not.toContain('stale-host');
+    expect(contents).toContain('JIRA_API_TOKEN=fresh-token');
+  });
+
+  it('removes the temp file if rename fails', () => {
+    const source = new HomeFileSource();
+    const renameSpy = jest.spyOn(fs, 'renameSync').mockImplementation(() => {
+      throw new Error('boom');
+    });
+    try {
+      expect(() => source.write(JIRA, 'host', 'x')).toThrow('boom');
+      const dir = path.join(tempHome, HOME_DIR_NAME);
+      const entries = fs.existsSync(dir) ? fs.readdirSync(dir) : [];
+      expect(entries.filter((e) => e.includes('.tmp-'))).toEqual([]);
+    } finally {
+      renameSpy.mockRestore();
+    }
+  });
+});

package/src/config/__tests__/sources/macos-keychain.test.ts

@@ -0,0 +1,136 @@
+import { MacosKeychainSource, SECURITY_BINARY, type KeychainDeps } from '../../sources/macos-keychain.js';
+import type { ProductDefinition } from '../../source.js';
+
+const JIRA: ProductDefinition = {
+  id: 'jira',
+  envVars: {
+    host: 'JIRA_HOST',
+    apiBasePath: 'JIRA_API_BASE_PATH',
+    token: 'JIRA_API_TOKEN',
+    defaultPageSize: 'JIRA_DEFAULT_PAGE_SIZE',
+  },
+};
+
+function makeDeps(overrides: Partial<KeychainDeps> = {}) {
+  return {
+    execFileSync: jest.fn(),
+    existsSync: jest.fn(() => true),
+    getPlatform: () => 'darwin' as NodeJS.Platform,
+    ...overrides,
+  };
+}
+
+describe('MacosKeychainSource', () => {
+  it('isAvailable is true on darwin when binary exists', () => {
+    expect(new MacosKeychainSource(makeDeps()).isAvailable()).toBe(true);
+  });
+
+  it('isAvailable is false off darwin', () => {
+    const deps = makeDeps({ getPlatform: () => 'linux' as NodeJS.Platform });
+    expect(new MacosKeychainSource(deps).isAvailable()).toBe(false);
+  });
+
+  it('isAvailable is false when binary is missing', () => {
+    const deps = makeDeps({ existsSync: jest.fn(() => false) });
+    expect(new MacosKeychainSource(deps).isAvailable()).toBe(false);
+  });
+
+  it('read returns token on success and strips trailing newline', () => {
+    const execFileSync = jest.fn().mockReturnValueOnce('secret-token\n');
+    const deps = makeDeps({ execFileSync: execFileSync as unknown as KeychainDeps['execFileSync'] });
+    const source = new MacosKeychainSource(deps);
+    expect(source.read(JIRA, 'token')).toBe('secret-token');
+    expect(execFileSync).toHaveBeenCalledWith(
+      SECURITY_BINARY,
+      ['find-generic-password', '-s', 'atlassian-dc-mcp', '-a', 'jira-token', '-w'],
+      expect.objectContaining({ encoding: 'utf8', timeout: 5000 }),
+    );
+  });
+
+  it('read returns undefined when security exits non-zero (not found)', () => {
+    const execFileSync = jest.fn().mockImplementationOnce(() => {
+      const err: NodeJS.ErrnoException & { status?: number } = new Error('not found');
+      err.status = 44;
+      throw err;
+    });
+    const source = new MacosKeychainSource(makeDeps({ execFileSync: execFileSync as any }));
+    expect(source.read(JIRA, 'token')).toBeUndefined();
+  });
+
+  it('read returns undefined when keychain is locked (non-44)', () => {
+    const execFileSync = jest.fn().mockImplementationOnce(() => {
+      const err: NodeJS.ErrnoException & { status?: number } = new Error('auth failed');
+      err.status = 128;
+      throw err;
+    });
+    const source = new MacosKeychainSource(makeDeps({ execFileSync: execFileSync as any }));
+    expect(source.read(JIRA, 'token')).toBeUndefined();
+  });
+
+  it('read returns undefined for non-token keys without invoking security', () => {
+    const execFileSync = jest.fn();
+    const source = new MacosKeychainSource(makeDeps({ execFileSync: execFileSync as any }));
+    expect(source.read(JIRA, 'host')).toBeUndefined();
+    expect(execFileSync).not.toHaveBeenCalled();
+  });
+
+  it('caches reads', () => {
+    const execFileSync = jest.fn().mockReturnValueOnce('cached\n');
+    const source = new MacosKeychainSource(makeDeps({ execFileSync: execFileSync as any }));
+    source.read(JIRA, 'token');
+    source.read(JIRA, 'token');
+    source.read(JIRA, 'token');
+    expect(execFileSync).toHaveBeenCalledTimes(1);
+  });
+
+  it('write uses -U flag', () => {
+    const execFileSync = jest.fn().mockReturnValueOnce('');
+    const source = new MacosKeychainSource(makeDeps({ execFileSync: execFileSync as any }));
+    source.write(JIRA, 'token', 'abc');
+    expect(execFileSync).toHaveBeenCalledWith(
+      SECURITY_BINARY,
+      ['add-generic-password', '-U', '-s', 'atlassian-dc-mcp', '-a', 'jira-token', '-w', 'abc'],
+      expect.objectContaining({ encoding: 'utf8' }),
+    );
+  });
+
+  it('write throws when the key is not token', () => {
+    const execFileSync = jest.fn();
+    const source = new MacosKeychainSource(makeDeps({ execFileSync: execFileSync as any }));
+    expect(() => source.write(JIRA, 'host', 'x')).toThrow(/only stores the token/);
+    expect(execFileSync).not.toHaveBeenCalled();
+  });
+
+  it('round-trips a token containing shell metacharacters', () => {
+    const tricky = 'a\'b"c$d`e';
+    const execFileSync = jest
+      .fn()
+      .mockImplementationOnce(() => '')
+      .mockImplementationOnce(() => `${tricky}\n`);
+    const source = new MacosKeychainSource(makeDeps({ execFileSync: execFileSync as any }));
+    source.write(JIRA, 'token', tricky);
+    expect(source.read(JIRA, 'token')).toBe(tricky);
+    const writeArgs = execFileSync.mock.calls[0][1] as string[];
+    expect(writeArgs[writeArgs.length - 1]).toBe(tricky);
+  });
+
+  it('clear invokes delete-generic-password and caches undefined', () => {
+    const execFileSync = jest.fn().mockImplementationOnce(() => '');
+    const source = new MacosKeychainSource(makeDeps({ execFileSync: execFileSync as any }));
+    source.clear(JIRA, 'token');
+    expect(execFileSync).toHaveBeenCalledWith(
+      SECURITY_BINARY,
+      ['delete-generic-password', '-s', 'atlassian-dc-mcp', '-a', 'jira-token'],
+      expect.any(Object),
+    );
+    expect(source.read(JIRA, 'token')).toBeUndefined();
+  });
+
+  it('clear swallows errors', () => {
+    const execFileSync = jest.fn().mockImplementationOnce(() => {
+      throw new Error('not found');
+    });
+    const source = new MacosKeychainSource(makeDeps({ execFileSync: execFileSync as any }));
+    expect(() => source.clear(JIRA, 'token')).not.toThrow();
+  });
+});

package/src/config/__tests__/sources/process-env.test.ts

@@ -0,0 +1,59 @@
+import { ProcessEnvSource } from '../../sources/process-env.js';
+import type { ProductDefinition } from '../../source.js';
+
+const JIRA: ProductDefinition = {
+  id: 'jira',
+  envVars: {
+    host: 'JIRA_HOST',
+    apiBasePath: 'JIRA_API_BASE_PATH',
+    token: 'JIRA_API_TOKEN',
+    defaultPageSize: 'JIRA_DEFAULT_PAGE_SIZE',
+  },
+};
+
+const CONFLUENCE: ProductDefinition = {
+  id: 'confluence',
+  envVars: {
+    host: 'CONFLUENCE_HOST',
+    apiBasePath: 'CONFLUENCE_API_BASE_PATH',
+    token: 'CONFLUENCE_API_TOKEN',
+    defaultPageSize: 'CONFLUENCE_DEFAULT_PAGE_SIZE',
+  },
+};
+
+describe('ProcessEnvSource', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+    delete process.env.JIRA_HOST;
+    delete process.env.JIRA_API_TOKEN;
+    delete process.env.CONFLUENCE_HOST;
+  });
+
+  afterAll(() => {
+    process.env = originalEnv;
+  });
+
+  it('maps product+key to the correct env var', () => {
+    process.env.JIRA_HOST = 'j-host';
+    process.env.JIRA_API_TOKEN = 'j-token';
+    process.env.CONFLUENCE_HOST = 'c-host';
+    const source = new ProcessEnvSource();
+    expect(source.read(JIRA, 'host')).toBe('j-host');
+    expect(source.read(JIRA, 'token')).toBe('j-token');
+    expect(source.read(CONFLUENCE, 'host')).toBe('c-host');
+  });
+
+  it('returns undefined for absent or whitespace-only values', () => {
+    const source = new ProcessEnvSource();
+    expect(source.read(JIRA, 'host')).toBeUndefined();
+    process.env.JIRA_HOST = '   ';
+    expect(source.read(JIRA, 'host')).toBeUndefined();
+  });
+
+  it('trims surrounding whitespace', () => {
+    process.env.JIRA_HOST = '  j-host  ';
+    expect(new ProcessEnvSource().read(JIRA, 'host')).toBe('j-host');
+  });
+});

package/src/config/index.ts

@@ -0,0 +1,8 @@
+export * from './source.js';
+export * from './registry.js';
+export * from './runtime-config.js';
+export * from './resolve-base.js';
+export { ProcessEnvSource } from './sources/process-env.js';
+export { EnvFileSource, ATLASSIAN_DC_MCP_CONFIG_FILE_ENV_VAR } from './sources/env-file.js';
+export { HomeFileSource, getHomeFilePath, HOME_DIR_NAME } from './sources/home-file.js';
+export { MacosKeychainSource, KEYCHAIN_SERVICE } from './sources/macos-keychain.js';