@atlassian-dc-mcp/common 0.17.0 → 0.18.0

package/src/__tests__/setup-cli.test.ts

@@ -2,7 +2,13 @@ import { DefaultConfigRegistry } from '../config/registry.js';
 import { HomeFileSource } from '../config/sources/home-file.js';
 import { MacosKeychainSource, type KeychainDeps } from '../config/sources/macos-keychain.js';
 import { ProcessEnvSource } from '../config/sources/process-env.js';
-import { runSetup, type SetupPrompts } from '../setup-cli.js';
+import {
+  runSetup,
+  type CredentialValidationContext,
+  type CredentialValidationResult,
+  type SetupPrompts,
+  type ValidateCredentials,
+} from '../setup-cli.js';
 import type { ConfigKey, ProductDefinition } from '../config/source.js';
 
 const JIRA: ProductDefinition = {
@@ -72,15 +78,69 @@ class FakeHomeFile extends HomeFileSource {
   }
 }
 
+class StubCredentialValidator {
+  readonly calls: CredentialValidationContext[] = [];
+  private readonly queue: CredentialValidationResult[] = [];
+  private fallback: CredentialValidationResult = { ok: true };
+
+  returns(result: CredentialValidationResult): this {
+    this.fallback = result;
+    return this;
+  }
+
+  reject(message: string): this {
+    return this.returns({ ok: false, message });
+  }
+
+  enqueue(...results: CredentialValidationResult[]): this {
+    this.queue.push(...results);
+    return this;
+  }
+
+  asFn(): ValidateCredentials {
+    return async (ctx) => {
+      this.calls.push(ctx);
+      return this.queue.shift() ?? this.fallback;
+    };
+  }
+}
+
+type ConfirmStub = (message: string, fallbackDefault?: boolean) => boolean;
+
+function scriptedConfirms(script: Record<string, boolean>): ConfirmStub {
+  return (message, fallbackDefault) => {
+    for (const [prefix, answer] of Object.entries(script)) {
+      if (message.startsWith(prefix)) return answer;
+    }
+    return fallbackDefault ?? false;
+  };
+}
+
 function makeRegistry(keychain: FakeKeychain, home: FakeHomeFile) {
   return new DefaultConfigRegistry([new ProcessEnvSource(), home, keychain]);
 }
 
-function makePrompts(overrides: Partial<SetupPrompts> = {}): SetupPrompts {
+const standardAnswers = {
+  host: 'j-host',
+  apiBasePath: '/rest/api/2',
+  pageSize: '25',
+  token: 'secret',
+};
+
+function makePrompts(
+  overrides: Partial<SetupPrompts> = {},
+  answers: Partial<typeof standardAnswers> = {},
+  confirms?: ConfirmStub,
+): SetupPrompts {
+  const filled = { ...standardAnswers, ...answers };
   return {
-    input: async (opts) => opts.default ?? '',
-    password: async () => '',
-    confirm: async (opts) => opts.default ?? false,
+    input: async (opts) => {
+      if (opts.message.startsWith('Host')) return filled.host;
+      if (opts.message.startsWith('API base path')) return filled.apiBasePath;
+      return filled.pageSize;
+    },
+    password: async () => filled.token,
+    confirm: async (opts) => (confirms ?? ((_m, d) => d ?? false))(opts.message, opts.default),
     ...overrides,
   };
 }
@@ -105,16 +165,13 @@ describe('runSetup', () => {
   });
 
   it('writes the token to keychain first on darwin and clears home file token', async () => {
-    const prompts = makePrompts({
-      input: async (opts) => {
-        if (opts.message.startsWith('Host')) return 'j-host';
-        if (opts.message.startsWith('API base path')) return '/rest/api/2';
-        return '25';
-      },
-      password: async () => 'secret',
-    });
     const registry = makeRegistry(keychain, home);
-    await runSetup(JIRA, { registry, log: (m) => logs.push(m), exit: () => undefined, prompts });
+    await runSetup(JIRA, {
+      registry,
+      log: (m) => logs.push(m),
+      exit: () => undefined,
+      prompts: makePrompts(),
+    });
 
     expect(keychain.writeCalls).toBe(1);
     expect(keychain.store).toBe('secret');
@@ -124,16 +181,13 @@ describe('runSetup', () => {
 
   it('falls back to home file when keychain is unavailable', async () => {
     keychain.available = false;
-    const prompts = makePrompts({
-      input: async (opts) => {
-        if (opts.message.startsWith('Host')) return 'j-host';
-        if (opts.message.startsWith('API base path')) return '/rest/api/2';
-        return '25';
-      },
-      password: async () => 'secret',
-    });
     const registry = makeRegistry(keychain, home);
-    await runSetup(JIRA, { registry, log: (m) => logs.push(m), exit: () => undefined, prompts });
+    await runSetup(JIRA, {
+      registry,
+      log: (m) => logs.push(m),
+      exit: () => undefined,
+      prompts: makePrompts(),
+    });
 
     expect(keychain.writeCalls).toBe(0);
     const tokenWrites = home.writes.filter(([, k]) => k === 'token');
@@ -142,32 +196,121 @@ describe('runSetup', () => {
 
   it('prints shadowing warning when env var is set higher than target', async () => {
     process.env.JIRA_API_TOKEN = 'shadow';
-    const prompts = makePrompts({
-      input: async (opts) => {
-        if (opts.message.startsWith('Host')) return 'j-host';
-        if (opts.message.startsWith('API base path')) return '/rest/api/2';
-        return '25';
-      },
-      password: async () => 'secret',
-    });
     const registry = makeRegistry(keychain, home);
-    await runSetup(JIRA, { registry, log: (m) => logs.push(m), exit: () => undefined, prompts });
+    await runSetup(JIRA, {
+      registry,
+      log: (m) => logs.push(m),
+      exit: () => undefined,
+      prompts: makePrompts(),
+    });
 
     expect(logs.some((l) => l.includes('JIRA_API_TOKEN') && l.includes('Warning'))).toBe(true);
   });
 
+  it('calls validateCredentials with the entered values before saving', async () => {
+    const validator = new StubCredentialValidator();
+    const registry = makeRegistry(keychain, home);
+
+    await runSetup(JIRA, {
+      registry,
+      log: (m) => logs.push(m),
+      exit: () => undefined,
+      prompts: makePrompts(),
+      validateCredentials: validator.asFn(),
+    });
+
+    expect(validator.calls).toEqual([
+      { host: 'j-host', apiBasePath: '/rest/api/2', token: 'secret' },
+    ]);
+    expect(keychain.writeCalls).toBe(1);
+  });
+
+  it('exits without writing when validation fails and user declines retry or save-anyway', async () => {
+    const validator = new StubCredentialValidator().reject('401 Unauthorized');
+    const exitFn = jest.fn();
+    const registry = makeRegistry(keychain, home);
+
+    await runSetup(JIRA, {
+      registry,
+      log: (m) => logs.push(m),
+      exit: exitFn,
+      prompts: makePrompts({}, { token: 'bad-token' }, scriptedConfirms({
+        'Try again': false,
+        'Save configuration anyway': false,
+      })),
+      validateCredentials: validator.asFn(),
+    });
+
+    expect(validator.calls).toHaveLength(1);
+    expect(exitFn).toHaveBeenCalledWith(1);
+    expect(keychain.writeCalls).toBe(0);
+    expect(home.writes).toHaveLength(0);
+    expect(logs.some((l) => l.includes('401 Unauthorized'))).toBe(true);
+  });
+
+  it('retries validation after a failure and writes once it succeeds', async () => {
+    const validator = new StubCredentialValidator().enqueue(
+      { ok: false, message: '401 Unauthorized' },
+      { ok: true },
+    );
+    const registry = makeRegistry(keychain, home);
+
+    await runSetup(JIRA, {
+      registry,
+      log: (m) => logs.push(m),
+      exit: () => undefined,
+      prompts: makePrompts({}, {}, scriptedConfirms({ 'Try again': true })),
+      validateCredentials: validator.asFn(),
+    });
+
+    expect(validator.calls).toHaveLength(2);
+    expect(keychain.writeCalls).toBe(1);
+    expect(logs.some((l) => l.includes('401 Unauthorized'))).toBe(true);
+    expect(logs.some((l) => l.startsWith('Validation succeeded'))).toBe(true);
+  });
+
+  it('stops offering retry after the third failure and lets the user save anyway', async () => {
+    const validator = new StubCredentialValidator().reject('401 Unauthorized');
+    let retryPromptsShown = 0;
+    const confirms: ConfirmStub = (message) => {
+      if (message.startsWith('Try again')) {
+        retryPromptsShown++;
+        return true;
+      }
+      if (message.startsWith('Save configuration anyway')) return true;
+      return false;
+    };
+    const registry = makeRegistry(keychain, home);
+
+    await runSetup(JIRA, {
+      registry,
+      log: (m) => logs.push(m),
+      exit: () => undefined,
+      prompts: makePrompts({}, {}, confirms),
+      validateCredentials: validator.asFn(),
+    });
+
+    expect(validator.calls).toHaveLength(3);
+    expect(retryPromptsShown).toBe(2);
+    expect(keychain.writeCalls).toBe(1);
+  });
+
   it('exits 130 on SIGINT cancellation before any write', async () => {
     const exitErr: Error & { name: string } = Object.assign(new Error('closed'), {
       name: 'ExitPromptError',
     });
-    const prompts = makePrompts({
-      input: async () => {
-        throw exitErr;
-      },
-    });
     const exitFn = jest.fn();
     const registry = makeRegistry(keychain, home);
-    await runSetup(JIRA, { registry, log: (m) => logs.push(m), exit: exitFn, prompts });
+    await runSetup(JIRA, {
+      registry,
+      log: (m) => logs.push(m),
+      exit: exitFn,
+      prompts: makePrompts({
+        input: async () => {
+          throw exitErr;
+        },
+      }),
+    });
     expect(exitFn).toHaveBeenCalledWith(130);
     expect(keychain.writeCalls).toBe(0);
     expect(home.writes).toHaveLength(0);

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/index.ts

@@ -1,6 +1,7 @@
 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';

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/source.ts

@@ -8,6 +8,7 @@ export interface ProductDefinition {
   readonly id: string;
   readonly envVars: Record<ConfigKey, string>;
   readonly defaultApiBasePath?: string;
+  readonly apiBasePathStrippableSuffixes?: readonly string[];
 }
 
 export interface ReadableSource {

package/src/index.ts

@@ -4,6 +4,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 export * from './api-error-handler.js'
 export * from './config/index.js';
 export { runSetup } from './setup-cli.js';
+export { describeValidationError } from './setup/describe-error.js';
 
 // Helper function to format tool responses
 export const formatToolResponse = (result: unknown) => ({

package/src/setup/describe-error.ts

@@ -0,0 +1,67 @@
+const NETWORK_CODE_HINTS: Record<string, string> = {
+  ENOTFOUND: 'could not resolve host',
+  EAI_AGAIN: 'DNS lookup temporarily failed',
+  ECONNREFUSED: 'connection refused',
+  ECONNRESET: 'connection reset by peer',
+  ETIMEDOUT: 'connection timed out',
+  ECONNABORTED: 'connection aborted',
+  EHOSTUNREACH: 'host is unreachable',
+  ENETUNREACH: 'network is unreachable',
+  EPROTO: 'TLS protocol error',
+  CERT_HAS_EXPIRED: 'server TLS certificate has expired',
+  DEPTH_ZERO_SELF_SIGNED_CERT: 'server uses a self-signed TLS certificate',
+  SELF_SIGNED_CERT_IN_CHAIN: 'server TLS certificate chain is self-signed',
+  UNABLE_TO_VERIFY_LEAF_SIGNATURE: 'server TLS certificate could not be verified',
+  ERR_TLS_CERT_ALTNAME_INVALID: 'server TLS certificate does not match the host name',
+};
+
+type ApiLikeError = {
+  status: number;
+  statusText?: string;
+  url?: string;
+  body?: unknown;
+};
+
+type CauseLikeError = {
+  code?: string;
+  message?: string;
+};
+
+export function describeValidationError(error: unknown): string {
+  if (isApiLikeError(error)) {
+    return formatApiError(error);
+  }
+  if (isAbortError(error)) {
+    return 'request was aborted (possibly timed out)';
+  }
+
+  const err = error as { message?: string; cause?: CauseLikeError } | undefined;
+  const cause = err?.cause;
+  if (cause?.code) {
+    const hint = NETWORK_CODE_HINTS[cause.code] ?? 'network error';
+    const detail = cause.message ?? err?.message ?? 'unknown';
+    return `${hint} (${cause.code}: ${detail})`;
+  }
+
+  return err?.message ?? String(error);
+}
+
+function formatApiError(error: ApiLikeError): string {
+  const status = `${error.status}${error.statusText ? ` ${error.statusText}` : ''}`.trim();
+  const url = error.url ? `${error.url} ` : '';
+  const hint = status.startsWith('401') || status.startsWith('403')
+    ? ' Check the host, API base path, and API token.'
+    : '';
+  return `${url}returned ${status}.${hint}`.trim();
+}
+
+function isApiLikeError(error: unknown): error is ApiLikeError {
+  return Boolean(error)
+    && typeof error === 'object'
+    && 'status' in (error as object)
+    && typeof (error as ApiLikeError).status === 'number';
+}
+
+function isAbortError(error: unknown): boolean {
+  return Boolean(error && typeof error === 'object' && (error as { name?: string }).name === 'AbortError');
+}

package/src/setup/value-validator.ts

@@ -0,0 +1,59 @@
+export type ValidationResult = true | string;
+
+export class SetupValueValidator {
+  static host(raw: string): ValidationResult {
+    const value = raw.trim();
+    if (value.length === 0) {
+      return true;
+    }
+    if (/\s/.test(value)) {
+      return 'must not contain whitespace';
+    }
+    try {
+      const url = new URL(/^https?:\/\//i.test(value) ? value : `https://${value}`);
+      if (!url.hostname) {
+        return 'must include a host name';
+      }
+      if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        return 'must use http or https';
+      }
+      return true;
+    } catch {
+      return 'enter a host name or http(s) URL';
+    }
+  }
+
+  static apiBasePath(raw: string): ValidationResult {
+    const value = raw.trim();
+    if (value.length === 0) {
+      return true;
+    }
+    if (/\s/.test(value)) {
+      return 'must not contain whitespace';
+    }
+    if (/^https?:\/\//i.test(value)) {
+      try {
+        new URL(value);
+        return true;
+      } catch {
+        return 'enter a valid http(s) URL';
+      }
+    }
+    return value.startsWith('/') ? true : 'enter a path starting with / or a full http(s) URL';
+  }
+
+  static token(raw: string): ValidationResult {
+    const value = raw.trim();
+    if (value.length === 0) {
+      return true;
+    }
+    return /\s/.test(value) ? 'must not contain whitespace' : true;
+  }
+
+  static pageSize(raw: string): ValidationResult {
+    const trimmed = raw.trim();
+    return /^\d+$/.test(trimmed) && Number.parseInt(trimmed, 10) > 0
+      ? true
+      : 'enter a positive integer';
+  }
+}