@atlassian-dc-mcp/common 0.17.1 → 0.19.0

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

@@ -2,9 +2,28 @@ 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 { ParsedSetupArgs } from '../setup/args.js';
 import type { ConfigKey, ProductDefinition } from '../config/source.js';
 
+function makeArgs(overrides: Partial<ParsedSetupArgs> = {}): ParsedSetupArgs {
+  return {
+    host: undefined,
+    apiBasePath: undefined,
+    token: undefined,
+    defaultPageSize: undefined,
+    nonInteractive: false,
+    help: false,
+    ...overrides,
+  };
+}
+
 const JIRA: ProductDefinition = {
   id: 'jira',
   envVars: {
@@ -72,15 +91,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 +178,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 +194,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,34 +209,322 @@ 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);
   });
+
+  it('skips the host prompt when --host is passed and still prompts for the rest', async () => {
+    const inputCalls: string[] = [];
+    const passwordCalls = jest.fn(async () => 'secret');
+    const registry = makeRegistry(keychain, home);
+
+    await runSetup(JIRA, {
+      registry,
+      log: (m) => logs.push(m),
+      exit: () => undefined,
+      args: makeArgs({ host: 'cli-host.example.com' }),
+      prompts: {
+        input: async (opts) => {
+          inputCalls.push(opts.message);
+          if (opts.message.startsWith('API base path')) return '/rest/api/2';
+          return '25';
+        },
+        password: passwordCalls,
+        confirm: async (opts) => opts.default ?? false,
+      },
+    });
+
+    expect(inputCalls.some((m) => m.startsWith('Host'))).toBe(false);
+    expect(inputCalls.some((m) => m.startsWith('API base path'))).toBe(true);
+    expect(passwordCalls).toHaveBeenCalledTimes(1);
+    expect(home.values.jira.host).toBe('cli-host.example.com');
+  });
+
+  describe('non-interactive mode', () => {
+    function nonInteractivePrompts(): SetupPrompts & { inputCalls: string[]; passwordCalls: number } {
+      const inputCalls: string[] = [];
+      let passwordCalls = 0;
+      return Object.assign(
+        {
+          input: async (opts: { message: string }) => {
+            inputCalls.push(opts.message);
+            return '';
+          },
+          password: async () => {
+            passwordCalls++;
+            return '';
+          },
+          confirm: async () => false,
+        },
+        {
+          inputCalls,
+          get passwordCalls() {
+            return passwordCalls;
+          },
+        },
+      ) as SetupPrompts & { inputCalls: string[]; passwordCalls: number };
+    }
+
+    it('writes everything without prompts when all required fields come from CLI args', async () => {
+      const validator = new StubCredentialValidator();
+      const exitFn = jest.fn();
+      const registry = makeRegistry(keychain, home);
+      const prompts = nonInteractivePrompts();
+
+      await runSetup(JIRA, {
+        registry,
+        log: (m) => logs.push(m),
+        exit: exitFn,
+        prompts,
+        validateCredentials: validator.asFn(),
+        args: makeArgs({
+          host: 'cli-host.example.com',
+          token: 'cli-token',
+          nonInteractive: true,
+        }),
+      });
+
+      expect(prompts.inputCalls).toHaveLength(0);
+      expect(prompts.passwordCalls).toBe(0);
+      expect(exitFn).not.toHaveBeenCalled();
+      expect(validator.calls).toEqual([
+        { host: 'cli-host.example.com', apiBasePath: '/rest/api/2', token: 'cli-token' },
+      ]);
+      expect(home.values.jira.host).toBe('cli-host.example.com');
+      expect(home.values.jira.apiBasePath).toBe('/rest/api/2');
+      expect(keychain.store).toBe('cli-token');
+    });
+
+    it('exits 1 when --token is missing and there is no existing token', async () => {
+      const validator = new StubCredentialValidator();
+      const exitFn = jest.fn();
+      const registry = makeRegistry(keychain, home);
+
+      await runSetup(JIRA, {
+        registry,
+        log: (m) => logs.push(m),
+        exit: exitFn,
+        prompts: nonInteractivePrompts(),
+        validateCredentials: validator.asFn(),
+        args: makeArgs({ host: 'cli-host.example.com', nonInteractive: true }),
+      });
+
+      expect(exitFn).toHaveBeenCalledWith(1);
+      expect(validator.calls).toHaveLength(0);
+      expect(keychain.writeCalls).toBe(0);
+      expect(home.writes).toHaveLength(0);
+      expect(logs.some((l) => l.includes('JIRA_API_TOKEN'))).toBe(true);
+    });
+
+    it('reuses an existing keychain token without rewriting it when --token is omitted', async () => {
+      keychain.store = 'kept-token';
+      const validator = new StubCredentialValidator();
+      const exitFn = jest.fn();
+      const registry = makeRegistry(keychain, home);
+
+      await runSetup(JIRA, {
+        registry,
+        log: (m) => logs.push(m),
+        exit: exitFn,
+        prompts: nonInteractivePrompts(),
+        validateCredentials: validator.asFn(),
+        args: makeArgs({ host: 'cli-host.example.com', nonInteractive: true }),
+      });
+
+      expect(exitFn).not.toHaveBeenCalled();
+      expect(validator.calls).toEqual([
+        { host: 'cli-host.example.com', apiBasePath: '/rest/api/2', token: 'kept-token' },
+      ]);
+      expect(keychain.writeCalls).toBe(0);
+      expect(keychain.store).toBe('kept-token');
+      const tokenWrites = home.writes.filter(([, k]) => k === 'token');
+      expect(tokenWrites).toHaveLength(0);
+    });
+
+    it('exits 1 with a format error when --default-page-size is not a positive integer', async () => {
+      const exitFn = jest.fn();
+      const registry = makeRegistry(keychain, home);
+
+      await runSetup(JIRA, {
+        registry,
+        log: (m) => logs.push(m),
+        exit: exitFn,
+        prompts: nonInteractivePrompts(),
+        args: makeArgs({
+          host: 'cli-host.example.com',
+          token: 'cli-token',
+          defaultPageSize: 'abc',
+          nonInteractive: true,
+        }),
+      });
+
+      expect(exitFn).toHaveBeenCalledWith(1);
+      expect(home.writes).toHaveLength(0);
+      expect(keychain.writeCalls).toBe(0);
+      expect(logs.some((l) => l.includes('default page size'))).toBe(true);
+    });
+
+    it('exits 1 on credential rejection without retrying or asking to save anyway', async () => {
+      const validator = new StubCredentialValidator().reject('401 Unauthorized');
+      const exitFn = jest.fn();
+      const confirmFn = jest.fn(async () => false);
+      const registry = makeRegistry(keychain, home);
+
+      await runSetup(JIRA, {
+        registry,
+        log: (m) => logs.push(m),
+        exit: exitFn,
+        prompts: { ...nonInteractivePrompts(), confirm: confirmFn },
+        validateCredentials: validator.asFn(),
+        args: makeArgs({
+          host: 'cli-host.example.com',
+          token: 'cli-token',
+          nonInteractive: true,
+        }),
+      });
+
+      expect(validator.calls).toHaveLength(1);
+      expect(exitFn).toHaveBeenCalledWith(1);
+      expect(confirmFn).not.toHaveBeenCalled();
+      expect(keychain.writeCalls).toBe(0);
+      expect(home.writes).toHaveLength(0);
+    });
+
+    it('falls back to product.defaultApiBasePath and FALLBACK_PAGE_SIZE for unspecified optional fields', async () => {
+      const validator = new StubCredentialValidator();
+      const registry = makeRegistry(keychain, home);
+
+      await runSetup(JIRA, {
+        registry,
+        log: (m) => logs.push(m),
+        exit: () => undefined,
+        prompts: nonInteractivePrompts(),
+        validateCredentials: validator.asFn(),
+        args: makeArgs({
+          host: 'cli-host.example.com',
+          token: 'cli-token',
+          nonInteractive: true,
+        }),
+      });
+
+      expect(home.values.jira.apiBasePath).toBe('/rest/api/2');
+      expect(home.values.jira.defaultPageSize).toBe('25');
+    });
+  });
 });

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

@@ -3,7 +3,9 @@ import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 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 { runSetup, runSetupCli } from './setup-cli.js';
+export { describeValidationError } from './setup/describe-error.js';
+export { parseSetupArgs, printSetupHelp, SetupArgsError, type ParsedSetupArgs } from './setup/args.js';
 
 // Helper function to format tool responses
 export const formatToolResponse = (result: unknown) => ({

package/src/setup/args.ts

@@ -0,0 +1,78 @@
+import { parseArgs } from 'node:util';
+
+export type ParsedSetupArgs = {
+  host?: string;
+  apiBasePath?: string;
+  token?: string;
+  defaultPageSize?: string;
+  nonInteractive: boolean;
+  help: boolean;
+};
+
+export class SetupArgsError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SetupArgsError';
+  }
+}
+
+export function parseSetupArgs(argv: readonly string[]): ParsedSetupArgs {
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args: [...argv],
+      options: {
+        host: { type: 'string', short: 'H' },
+        'api-base-path': { type: 'string', short: 'b' },
+        token: { type: 'string', short: 't' },
+        'default-page-size': { type: 'string', short: 's' },
+        'non-interactive': { type: 'boolean', short: 'n', default: false },
+        help: { type: 'boolean', short: 'h', default: false },
+      },
+      strict: true,
+      allowPositionals: false,
+    }));
+  } catch (error) {
+    throw new SetupArgsError((error as Error).message);
+  }
+
+  return {
+    host: trimToUndefined(values.host),
+    apiBasePath: trimToUndefined(values['api-base-path']),
+    token: trimToUndefined(values.token),
+    defaultPageSize: trimToUndefined(values['default-page-size']),
+    nonInteractive: values['non-interactive'] === true,
+    help: values.help === true,
+  };
+}
+
+function trimToUndefined(value: string | undefined): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed.length === 0 ? undefined : trimmed;
+}
+
+export function printSetupHelp(productId: string, log: (message: string) => void): void {
+  const lines = [
+    `Usage: @atlassian-dc-mcp/${productId} setup [options]`,
+    '',
+    'Options:',
+    '  -H, --host <value>          Host (e.g. jira.example.com)',
+    '  -b, --api-base-path <value> API base path or full URL',
+    '  -t, --token <value>         API token',
+    '  -s, --default-page-size <n> Default page size (positive integer)',
+    '  -n, --non-interactive       Skip prompts; fail if a required value is missing',
+    '  -h, --help                  Show this help and exit',
+    '',
+    'In interactive mode (default), any value not passed as a flag is collected via prompts.',
+    'In --non-interactive mode, missing values fall back to existing configuration',
+    `(process env, ~/.atlassian-dc-mcp/${productId}.env, or macOS Keychain), and the run`,
+    'fails if a host (or full-URL --api-base-path) and token cannot be resolved.',
+    'An existing token is reused when --token is omitted.',
+  ];
+  for (const line of lines) {
+    log(line);
+  }
+}

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');
+}