@atlassian-dc-mcp/common 0.16.0 → 0.17.1

package/src/config/registry.ts

@@ -0,0 +1,79 @@
+import type {
+  ConfigKey,
+  ProductDefinition,
+  ReadableSource,
+  SourceLocation,
+  WritableSource,
+} from './source.js';
+import { isWritableSource } from './source.js';
+import { ProcessEnvSource } from './sources/process-env.js';
+import { EnvFileSource } from './sources/env-file.js';
+import { HomeFileSource } from './sources/home-file.js';
+import { MacosKeychainSource } from './sources/macos-keychain.js';
+
+export interface ResolvedValue {
+  value: string | undefined;
+  from?: SourceLocation;
+}
+
+export interface ConfigRegistry {
+  readonly sources: readonly ReadableSource[];
+  initialize(options?: { cwd?: string }): void;
+  resolve(product: ProductDefinition, key: ConfigKey): ResolvedValue;
+  locate(product: ProductDefinition, key: ConfigKey): SourceLocation[];
+  getWritableSource<T extends WritableSource>(predicate: (s: WritableSource) => s is T): T | undefined;
+}
+
+export class DefaultConfigRegistry implements ConfigRegistry {
+  readonly sources: readonly ReadableSource[];
+
+  constructor(sources: ReadableSource[]) {
+    this.sources = [...sources].sort((a, b) => b.priority - a.priority);
+  }
+
+  initialize(options?: { cwd?: string }): void {
+    for (const source of this.sources) {
+      source.initialize?.(options);
+    }
+  }
+
+  resolve(product: ProductDefinition, key: ConfigKey): ResolvedValue {
+    for (const source of this.sources) {
+      const value = source.read(product, key);
+      if (value !== undefined) {
+        return { value, from: { sourceId: source.id, detail: source.describe() } };
+      }
+    }
+    return { value: undefined };
+  }
+
+  locate(product: ProductDefinition, key: ConfigKey): SourceLocation[] {
+    const locations: SourceLocation[] = [];
+    for (const source of this.sources) {
+      if (source.read(product, key) !== undefined) {
+        locations.push({ sourceId: source.id, detail: source.describe() });
+      }
+    }
+    return locations;
+  }
+
+  getWritableSource<T extends WritableSource>(
+    predicate: (s: WritableSource) => s is T,
+  ): T | undefined {
+    for (const source of this.sources) {
+      if (isWritableSource(source) && predicate(source)) {
+        return source;
+      }
+    }
+    return undefined;
+  }
+}
+
+export function buildDefaultRegistry(): DefaultConfigRegistry {
+  return new DefaultConfigRegistry([
+    new ProcessEnvSource(),
+    new EnvFileSource(),
+    new HomeFileSource(),
+    new MacosKeychainSource(),
+  ]);
+}

package/src/config/resolve-base.ts

@@ -0,0 +1,43 @@
+export type ResolveOpenApiBaseOptions = {
+  host?: string;
+  apiBasePath?: string;
+  defaultBasePath: string;
+  strippableSuffixes?: readonly string[];
+};
+
+function normalizeHost(host: string): string {
+  const withScheme = /^https?:\/\//i.test(host) ? host : `https://${host}`;
+  return withScheme.replace(/\/+$/, '');
+}
+
+function stripGeneratedSuffix(path: string, suffixes: readonly string[]): string {
+  for (const suffix of suffixes) {
+    const escaped = suffix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(`${escaped}\\/?$`, 'i');
+    if (re.test(path)) {
+      return path.replace(re, '');
+    }
+  }
+  return path;
+}
+
+function normalizeBasePath(path: string, suffixes: readonly string[]): string {
+  const stripped = stripGeneratedSuffix(path, suffixes).replace(/\/+$/, '');
+  return stripped === '/' ? '' : stripped;
+}
+
+export function resolveOpenApiBase(options: ResolveOpenApiBaseOptions): string {
+  const { host, apiBasePath, defaultBasePath, strippableSuffixes = [] } = options;
+
+  if (apiBasePath && /^https?:\/\//i.test(apiBasePath)) {
+    const url = new URL(apiBasePath);
+    return `${url.origin}${normalizeBasePath(url.pathname, strippableSuffixes)}`;
+  }
+
+  if (!host) {
+    throw new Error('host or apiBasePath must be provided');
+  }
+
+  const basePath = apiBasePath ? normalizeBasePath(apiBasePath, strippableSuffixes) : defaultBasePath;
+  return `${normalizeHost(host)}${basePath}`;
+}

package/src/config/runtime-config.ts

@@ -0,0 +1,60 @@
+import { buildDefaultRegistry, type ConfigRegistry } from './registry.js';
+import type { ConfigKey, ProductDefinition } from './source.js';
+
+const FALLBACK_PAGE_SIZE = 25;
+
+export type ProductRuntimeConfig = {
+  host?: string;
+  apiBasePath?: string;
+  token?: string;
+  defaultPageSize: number;
+};
+
+export { ATLASSIAN_DC_MCP_CONFIG_FILE_ENV_VAR } from './sources/env-file.js';
+
+let registry: ConfigRegistry = buildDefaultRegistry();
+
+export function initializeRuntimeConfig(options?: { cwd?: string }): void {
+  registry.initialize(options);
+}
+
+function resolveString(product: ProductDefinition, key: ConfigKey): string | undefined {
+  return registry.resolve(product, key).value;
+}
+
+function parsePositiveInteger(value: string | undefined): number | undefined {
+  if (!value) {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  if (!/^\d+$/.test(trimmed)) {
+    return undefined;
+  }
+  const parsed = Number.parseInt(trimmed, 10);
+  return parsed > 0 ? parsed : undefined;
+}
+
+export function getProductRuntimeConfig(product: ProductDefinition): ProductRuntimeConfig {
+  return {
+    host: resolveString(product, 'host'),
+    apiBasePath: resolveString(product, 'apiBasePath'),
+    token: resolveString(product, 'token'),
+    defaultPageSize:
+      parsePositiveInteger(resolveString(product, 'defaultPageSize')) ?? FALLBACK_PAGE_SIZE,
+  };
+}
+
+export function validateProductRuntimeConfig(product: ProductDefinition): string[] {
+  const config = getProductRuntimeConfig(product);
+  const missing: string[] = [];
+
+  if (!config.token) {
+    missing.push(product.envVars.token);
+  }
+
+  if (!config.host && !config.apiBasePath) {
+    missing.push(`${product.envVars.host} or ${product.envVars.apiBasePath}`);
+  }
+
+  return missing;
+}

package/src/config/source.ts

@@ -0,0 +1,37 @@
+export type ConfigKey = 'host' | 'apiBasePath' | 'token' | 'defaultPageSize';
+
+export type SourceId = 'process-env' | 'env-file' | 'home-file' | 'macos-keychain';
+
+export type SourceLocation = { sourceId: SourceId; detail?: string };
+
+export interface ProductDefinition {
+  readonly id: string;
+  readonly envVars: Record<ConfigKey, string>;
+  readonly defaultApiBasePath?: string;
+}
+
+export interface ReadableSource {
+  readonly id: SourceId;
+  readonly priority: number;
+  read(product: ProductDefinition, key: ConfigKey): string | undefined;
+  initialize?(options?: { cwd?: string }): void;
+  describe(): string;
+}
+
+export interface WritableSource extends ReadableSource {
+  isAvailable(): boolean;
+  write(product: ProductDefinition, key: ConfigKey, value: string): void;
+  clear(product: ProductDefinition, key: ConfigKey): void;
+}
+
+export function isWritableSource(source: ReadableSource): source is WritableSource {
+  return typeof (source as WritableSource).write === 'function';
+}
+
+export function getNonEmptyValue(value: string | undefined): string | undefined {
+  if (!value) {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}

package/src/config/sources/dotenv-file-cache.ts

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import dotenv from 'dotenv';
+
+export type ParsedEnvironment = Record<string, string>;
+
+type CacheEntry = {
+  filePath: string;
+  mtimeMs: number;
+  values: ParsedEnvironment;
+};
+
+export class DotenvFileNotFoundError extends Error {
+  readonly filePath: string;
+  constructor(filePath: string) {
+    super(`Dotenv file not found: ${filePath}`);
+    this.name = 'DotenvFileNotFoundError';
+    this.filePath = filePath;
+  }
+}
+
+export class DotenvFileCache {
+  private entry?: CacheEntry;
+
+  get filePath(): string | undefined {
+    return this.entry?.filePath;
+  }
+
+  load(filePath: string): ParsedEnvironment {
+    let stats: fs.Stats;
+    try {
+      stats = fs.statSync(filePath);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        if (this.entry?.filePath === filePath) {
+          this.entry = undefined;
+        }
+        throw new DotenvFileNotFoundError(filePath);
+      }
+      throw error;
+    }
+
+    if (this.entry && this.entry.filePath === filePath && this.entry.mtimeMs === stats.mtimeMs) {
+      return this.entry.values;
+    }
+
+    const values = dotenv.parse(fs.readFileSync(filePath));
+    this.entry = { filePath, mtimeMs: stats.mtimeMs, values };
+    return values;
+  }
+
+  invalidate(): void {
+    this.entry = undefined;
+  }
+}

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

@@ -0,0 +1,61 @@
+import path from 'node:path';
+import type { ConfigKey, ProductDefinition, ReadableSource, SourceId } from '../source.js';
+import { getNonEmptyValue } from '../source.js';
+import {
+  DotenvFileCache,
+  DotenvFileNotFoundError,
+  type ParsedEnvironment,
+} from './dotenv-file-cache.js';
+
+export const ATLASSIAN_DC_MCP_CONFIG_FILE_ENV_VAR = 'ATLASSIAN_DC_MCP_CONFIG_FILE';
+
+export class EnvFileSource implements ReadableSource {
+  readonly id: SourceId = 'env-file';
+  readonly priority = 80;
+
+  private cwd: string = process.cwd();
+  private cache = new DotenvFileCache();
+
+  initialize(options?: { cwd?: string }): void {
+    this.cwd = options?.cwd ?? process.cwd();
+    this.loadFile();
+  }
+
+  read(product: ProductDefinition, key: ConfigKey): string | undefined {
+    const values = this.loadFile();
+    return getNonEmptyValue(values[product.envVars[key]]);
+  }
+
+  describe(): string {
+    return this.cache.filePath ? `env-file (${this.cache.filePath})` : 'env-file';
+  }
+
+  private getExplicitFilePath(): string | undefined {
+    const filePath = getNonEmptyValue(process.env[ATLASSIAN_DC_MCP_CONFIG_FILE_ENV_VAR]);
+    if (!filePath) {
+      return undefined;
+    }
+    if (!path.isAbsolute(filePath)) {
+      throw new Error(`${ATLASSIAN_DC_MCP_CONFIG_FILE_ENV_VAR} must be an absolute path: ${filePath}`);
+    }
+    return filePath;
+  }
+
+  private loadFile(): ParsedEnvironment {
+    const explicitFilePath = this.getExplicitFilePath();
+    const filePath = explicitFilePath ?? path.join(this.cwd, '.env');
+    try {
+      return this.cache.load(filePath);
+    } catch (error) {
+      if (error instanceof DotenvFileNotFoundError) {
+        if (explicitFilePath) {
+          throw new Error(
+            `${ATLASSIAN_DC_MCP_CONFIG_FILE_ENV_VAR} points to a missing file: ${error.filePath}`,
+          );
+        }
+        return {};
+      }
+      throw error;
+    }
+  }
+}

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

@@ -0,0 +1,121 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import type { ConfigKey, ProductDefinition, SourceId, WritableSource } from '../source.js';
+import { getNonEmptyValue } from '../source.js';
+import {
+  DotenvFileCache,
+  DotenvFileNotFoundError,
+  type ParsedEnvironment,
+} from './dotenv-file-cache.js';
+
+const HOME_DIR_NAME = '.atlassian-dc-mcp';
+
+function getHomeFilePath(product: ProductDefinition | string): string {
+  const id = typeof product === 'string' ? product : product.id;
+  return path.join(os.homedir(), HOME_DIR_NAME, `${id}.env`);
+}
+
+function needsQuoting(value: string): boolean {
+  return /[\s#'"]/.test(value);
+}
+
+function serializeValue(value: string): string {
+  if (!needsQuoting(value)) {
+    return value;
+  }
+  return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+function serialize(values: ParsedEnvironment): string {
+  const lines: string[] = [];
+  for (const [key, raw] of Object.entries(values)) {
+    lines.push(`${key}=${serializeValue(raw)}`);
+  }
+  return lines.length > 0 ? `${lines.join('\n')}\n` : '';
+}
+
+export class HomeFileSource implements WritableSource {
+  readonly id: SourceId = 'home-file';
+  readonly priority = 60;
+
+  private cache = new DotenvFileCache();
+
+  isAvailable(): boolean {
+    return true;
+  }
+
+  read(product: ProductDefinition, key: ConfigKey): string | undefined {
+    const values = this.loadFile(product);
+    return getNonEmptyValue(values[product.envVars[key]]);
+  }
+
+  describe(): string {
+    return `home-file (~/${HOME_DIR_NAME}/<product>.env)`;
+  }
+
+  describeForProduct(product: ProductDefinition): string {
+    return `home-file (${getHomeFilePath(product)})`;
+  }
+
+  write(product: ProductDefinition, key: ConfigKey, value: string): void {
+    const envVar = product.envVars[key];
+    const existing = this.readFileIgnoringErrors(product);
+    existing[envVar] = value;
+    this.persist(product, existing);
+  }
+
+  clear(product: ProductDefinition, key: ConfigKey): void {
+    const envVar = product.envVars[key];
+    const existing = this.readFileIgnoringErrors(product);
+    if (!(envVar in existing)) {
+      return;
+    }
+    delete existing[envVar];
+    this.persist(product, existing);
+  }
+
+  private loadFile(product: ProductDefinition): ParsedEnvironment {
+    const filePath = getHomeFilePath(product);
+    try {
+      return this.cache.load(filePath);
+    } catch (error) {
+      if (error instanceof DotenvFileNotFoundError) {
+        return {};
+      }
+      throw error;
+    }
+  }
+
+  private readFileIgnoringErrors(product: ProductDefinition): ParsedEnvironment {
+    try {
+      return { ...this.loadFile(product) };
+    } catch {
+      return {};
+    }
+  }
+
+  private persist(product: ProductDefinition, values: ParsedEnvironment): void {
+    const filePath = getHomeFilePath(product);
+    const dir = path.dirname(filePath);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+    const tmpPath = `${filePath}.tmp-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+    try {
+      fs.writeFileSync(tmpPath, serialize(values), { mode: 0o600 });
+      fs.renameSync(tmpPath, filePath);
+    } catch (error) {
+      try {
+        fs.unlinkSync(tmpPath);
+      } catch {
+        // best-effort cleanup
+      }
+      throw error;
+    }
+
+    this.cache.invalidate();
+  }
+}
+
+export { getHomeFilePath, HOME_DIR_NAME };

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

@@ -0,0 +1,117 @@
+import { execFileSync as nodeExecFileSync } from 'node:child_process';
+import { existsSync as nodeExistsSync } from 'node:fs';
+import type { ConfigKey, ProductDefinition, SourceId, WritableSource } from '../source.js';
+
+// We pass the token via `-w <value>` on write. `security add-generic-password`
+// has no stdin-password mode, so the token is visible in argv to same-user
+// processes. A same-user attacker already has keychain access via `security`
+// itself; this does not widen the attack surface.
+
+export const SECURITY_BINARY = '/usr/bin/security';
+export const KEYCHAIN_SERVICE = 'atlassian-dc-mcp';
+const KEYCHAIN_TIMEOUT_MS = 5000;
+export const NOT_FOUND_STATUS = 44;
+
+export type KeychainDeps = {
+  execFileSync: typeof nodeExecFileSync;
+  existsSync: typeof nodeExistsSync;
+  getPlatform: () => NodeJS.Platform;
+};
+
+function accountFor(product: ProductDefinition): string {
+  return `${product.id}-token`;
+}
+
+const DEFAULT_DEPS: KeychainDeps = {
+  execFileSync: nodeExecFileSync,
+  existsSync: nodeExistsSync,
+  getPlatform: () => process.platform,
+};
+
+export class MacosKeychainSource implements WritableSource {
+  readonly id: SourceId = 'macos-keychain';
+  readonly priority = 40;
+
+  private cache = new Map<string, string | undefined>();
+  private cacheWarmed = new Set<string>();
+  private readonly deps: KeychainDeps;
+
+  constructor(deps: Partial<KeychainDeps> = {}) {
+    this.deps = { ...DEFAULT_DEPS, ...deps };
+  }
+
+  isAvailable(): boolean {
+    return this.deps.getPlatform() === 'darwin' && this.deps.existsSync(SECURITY_BINARY);
+  }
+
+  read(product: ProductDefinition, key: ConfigKey): string | undefined {
+    if (key !== 'token' || !this.isAvailable()) {
+      return undefined;
+    }
+    if (this.cacheWarmed.has(product.id)) {
+      return this.cache.get(product.id);
+    }
+    const value = this.findPassword(product);
+    this.cache.set(product.id, value);
+    this.cacheWarmed.add(product.id);
+    return value;
+  }
+
+  describe(): string {
+    return 'macOS Keychain';
+  }
+
+  write(product: ProductDefinition, key: ConfigKey, value: string): void {
+    if (key !== 'token') {
+      throw new Error('macOS Keychain only stores the token key');
+    }
+    if (!this.isAvailable()) {
+      throw new Error('macOS Keychain is not available on this platform');
+    }
+    this.deps.execFileSync(
+      SECURITY_BINARY,
+      [
+        'add-generic-password',
+        '-U',
+        '-s', KEYCHAIN_SERVICE,
+        '-a', accountFor(product),
+        '-w', value,
+      ],
+      { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8', timeout: KEYCHAIN_TIMEOUT_MS },
+    );
+    this.cache.set(product.id, value);
+    this.cacheWarmed.add(product.id);
+  }
+
+  clear(product: ProductDefinition, key: ConfigKey): void {
+    if (key !== 'token' || !this.isAvailable()) {
+      return;
+    }
+    try {
+      this.deps.execFileSync(
+        SECURITY_BINARY,
+        ['delete-generic-password', '-s', KEYCHAIN_SERVICE, '-a', accountFor(product)],
+        { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8', timeout: KEYCHAIN_TIMEOUT_MS },
+      );
+    } catch {
+      // absent / already cleared — non-fatal
+    }
+    this.cache.set(product.id, undefined);
+    this.cacheWarmed.add(product.id);
+  }
+
+  private findPassword(product: ProductDefinition): string | undefined {
+    try {
+      const stdout = this.deps.execFileSync(
+        SECURITY_BINARY,
+        ['find-generic-password', '-s', KEYCHAIN_SERVICE, '-a', accountFor(product), '-w'],
+        { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8', timeout: KEYCHAIN_TIMEOUT_MS },
+      );
+      return String(stdout).replace(/\n$/, '');
+    } catch {
+      // exit 44 = not found; any other failure (locked keychain, etc.) is
+      // treated as absent so the resolver continues down the chain.
+      return undefined;
+    }
+  }
+}

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

@@ -0,0 +1,15 @@
+import type { ConfigKey, ProductDefinition, ReadableSource, SourceId } from '../source.js';
+import { getNonEmptyValue } from '../source.js';
+
+export class ProcessEnvSource implements ReadableSource {
+  readonly id: SourceId = 'process-env';
+  readonly priority = 100;
+
+  read(product: ProductDefinition, key: ConfigKey): string | undefined {
+    return getNonEmptyValue(process.env[product.envVars[key]]);
+  }
+
+  describe(): string {
+    return 'process env';
+  }
+}

package/src/index.ts

@@ -2,7 +2,8 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 export * from './api-error-handler.js'
-export * from './runtime-config.js';
+export * from './config/index.js';
+export { runSetup } from './setup-cli.js';
 
 // Helper function to format tool responses
 export const formatToolResponse = (result: unknown) => ({