@atlassian-dc-mcp/common 0.17.1 → 0.19.0

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

package/src/setup-cli.ts

@@ -1,6 +1,6 @@
 import { confirm as inquirerConfirm, input as inquirerInput, password as inquirerPassword } from '@inquirer/prompts';
 import { buildDefaultRegistry, type ConfigRegistry } from './config/registry.js';
-import { getProductRuntimeConfig } from './config/runtime-config.js';
+import type { ProductRuntimeConfig } from './config/runtime-config.js';
 import type {
   ConfigKey,
   ProductDefinition,
@@ -8,19 +8,46 @@ import type {
 } from './config/source.js';
 import { HomeFileSource, getHomeFilePath } from './config/sources/home-file.js';
 import { MacosKeychainSource } from './config/sources/macos-keychain.js';
+import { parseSetupArgs, printSetupHelp, SetupArgsError, type ParsedSetupArgs } from './setup/args.js';
+import { SetupValueValidator } from './setup/value-validator.js';
 
 const FALLBACK_PAGE_SIZE = 25;
+const MAX_VALIDATION_ATTEMPTS = 3;
+
+type PromptDefaults = {
+  host?: string;
+  apiBasePath?: string;
+  token?: string;
+  defaultPageSize?: number;
+};
 
 type PromptResult = {
   host: string;
   apiBasePath: string;
   defaultPageSize: string;
-  token: string | undefined;
+  tokenToWrite: string | undefined;
+  tokenForValidation: string | undefined;
+};
+
+type TokenPromptResult = Pick<PromptResult, 'tokenToWrite' | 'tokenForValidation'>;
+
+export type CredentialValidationContext = {
+  host: string;
+  apiBasePath: string;
+  token: string;
 };
 
+export type CredentialValidationResult =
+  | { ok: true; detail?: string }
+  | { ok: false; message: string };
+
+export type ValidateCredentials = (
+  context: CredentialValidationContext,
+) => Promise<CredentialValidationResult>;
+
 export type SetupPrompts = {
   input: (opts: { message: string; default?: string; validate?: (raw: string) => true | string }) => Promise<string>;
-  password: (opts: { message: string; mask?: string }) => Promise<string>;
+  password: (opts: { message: string; mask?: string; validate?: (raw: string) => true | string }) => Promise<string>;
   confirm: (opts: { message: string; default?: boolean }) => Promise<boolean>;
 };
 
@@ -29,6 +56,8 @@ export type SetupDeps = {
   log?: (message: string) => void;
   exit?: (code: number) => void;
   prompts?: SetupPrompts;
+  validateCredentials?: ValidateCredentials;
+  args?: ParsedSetupArgs;
 };
 
 const DEFAULT_PROMPTS: SetupPrompts = {
@@ -37,6 +66,36 @@ const DEFAULT_PROMPTS: SetupPrompts = {
   confirm: (opts) => inquirerConfirm(opts as any),
 };
 
+export async function runSetupCli(
+  product: ProductDefinition,
+  deps: Omit<SetupDeps, 'args'> = {},
+): Promise<void> {
+  const rawArgv = process.argv.slice(2);
+  const argv = rawArgv[0] === 'setup' ? rawArgv.slice(1) : rawArgv;
+  const exit = deps.exit ?? ((code: number) => { process.exit(code); });
+
+  let args: ParsedSetupArgs;
+  try {
+    args = parseSetupArgs(argv);
+  } catch (error) {
+    if (error instanceof SetupArgsError) {
+      process.stderr.write(`${error.message}\n\n`);
+      printSetupHelp(product.id, (m) => process.stderr.write(`${m}\n`));
+      exit(1);
+      return;
+    }
+    throw error;
+  }
+
+  if (args.help) {
+    printSetupHelp(product.id, (m) => process.stdout.write(`${m}\n`));
+    exit(0);
+    return;
+  }
+
+  await runSetup(product, { ...deps, args });
+}
+
 export async function runSetup(product: ProductDefinition, deps: SetupDeps = {}): Promise<void> {
   const registry = deps.registry ?? buildDefaultRegistry();
   const log = deps.log ?? ((message: string) => process.stdout.write(`${message}\n`));
@@ -48,26 +107,195 @@ export async function runSetup(product: ProductDefinition, deps: SetupDeps = {})
   log(`Atlassian DC MCP setup — ${product.id}`);
   log('');
 
-  const current = getProductRuntimeConfig(product);
+  const current = readCurrentConfig(registry, product);
   printCurrent(log, registry, product, current);
 
-  let answers: PromptResult;
-  try {
-    answers = await promptForValues(prompts, product, current);
-  } catch (error) {
-    if (isUserCancel(error)) {
-      exit(130);
-      return;
-    }
-    throw error;
+  const answers = deps.args?.nonInteractive
+    ? await runNonInteractive(product, deps, current, log, exit, deps.args)
+    : await collectAnswersWithValidation(product, deps, prompts, current, log, exit, deps.args);
+  if (!answers) {
+    return;
   }
 
   const homeFile = requireHomeFile(registry);
   writeNonSecretFields(registry, product, answers, homeFile, log);
-  const tokenWriter = await writeToken(registry, product, answers.token, homeFile, log, prompts);
+  const tokenWriter = await writeToken(registry, product, answers.tokenToWrite, homeFile, log, prompts);
   printSummary(log, product, answers, tokenWriter);
 }
 
+async function collectAnswersWithValidation(
+  product: ProductDefinition,
+  deps: SetupDeps,
+  prompts: SetupPrompts,
+  current: ProductRuntimeConfig,
+  log: (message: string) => void,
+  exit: (code: number) => void,
+  args: ParsedSetupArgs | undefined,
+): Promise<PromptResult | undefined> {
+  let defaults: PromptDefaults = current;
+
+  for (let attempt = 1; ; attempt++) {
+    let answers: PromptResult;
+    try {
+      answers = await promptForValues(prompts, product, defaults, args);
+    } catch (error) {
+      if (isUserCancel(error)) {
+        exit(130);
+        return undefined;
+      }
+      throw error;
+    }
+
+    const answerErrors = validateAnswers(product, answers);
+    if (answerErrors.length > 0) {
+      for (const message of answerErrors) {
+        log(`Validation failed: ${message}`);
+      }
+      const retry = await confirmRetry(prompts, 'Try again?');
+      if (retry) {
+        defaults = answersAsDefaults(answers);
+        continue;
+      }
+      exit(1);
+      return undefined;
+    }
+
+    if (!deps.validateCredentials || !answers.tokenForValidation) {
+      return answers;
+    }
+
+    const result = await deps.validateCredentials({
+      host: answers.host,
+      apiBasePath: answers.apiBasePath,
+      token: answers.tokenForValidation,
+    });
+    if (result.ok) {
+      log(result.detail ? `Validation succeeded: ${result.detail}` : 'Validation succeeded.');
+      return answers;
+    }
+
+    log(`Validation failed: ${result.message}`);
+    const outcome = await offerRetryAfterFailure(prompts, attempt);
+    if (outcome === 'retry') {
+      defaults = answersAsDefaults(answers);
+      continue;
+    }
+    if (outcome === 'save-anyway') {
+      return answers;
+    }
+    exit(1);
+    return undefined;
+  }
+}
+
+async function runNonInteractive(
+  product: ProductDefinition,
+  deps: SetupDeps,
+  current: ProductRuntimeConfig,
+  log: (message: string) => void,
+  exit: (code: number) => void,
+  args: ParsedSetupArgs,
+): Promise<PromptResult | undefined> {
+  let tokenToWrite: string | undefined;
+  let tokenForValidation: string | undefined;
+  if (args.token) {
+    tokenToWrite = args.token;
+    tokenForValidation = args.token;
+  } else if (current.token) {
+    tokenForValidation = current.token;
+  }
+
+  const answers: PromptResult = {
+    host: args.host ?? current.host ?? '',
+    apiBasePath: args.apiBasePath ?? current.apiBasePath ?? product.defaultApiBasePath ?? '',
+    defaultPageSize: args.defaultPageSize ?? String(current.defaultPageSize ?? FALLBACK_PAGE_SIZE),
+    tokenToWrite,
+    tokenForValidation,
+  };
+
+  const formatErrors = validateAnswers(product, answers);
+  if (formatErrors.length > 0) {
+    for (const message of formatErrors) {
+      log(`Validation failed: ${message}`);
+    }
+    exit(1);
+    return undefined;
+  }
+
+  if (deps.validateCredentials && answers.tokenForValidation) {
+    const result = await deps.validateCredentials({
+      host: answers.host,
+      apiBasePath: answers.apiBasePath,
+      token: answers.tokenForValidation,
+    });
+    if (!result.ok) {
+      log(`Validation failed: ${result.message}`);
+      exit(1);
+      return undefined;
+    }
+    log(result.detail ? `Validation succeeded: ${result.detail}` : 'Validation succeeded.');
+  }
+
+  return answers;
+}
+
+function answersAsDefaults(answers: PromptResult): PromptDefaults {
+  const pageSize = Number.parseInt(answers.defaultPageSize, 10);
+  return {
+    host: answers.host,
+    apiBasePath: answers.apiBasePath,
+    token: answers.tokenForValidation,
+    defaultPageSize: Number.isFinite(pageSize) && pageSize > 0 ? pageSize : undefined,
+  };
+}
+
+async function confirmRetry(prompts: SetupPrompts, message: string): Promise<boolean> {
+  return prompts.confirm({ message, default: true });
+}
+
+async function offerRetryAfterFailure(
+  prompts: SetupPrompts,
+  attempt: number,
+): Promise<'retry' | 'save-anyway' | 'abort'> {
+  if (attempt < MAX_VALIDATION_ATTEMPTS) {
+    const retry = await confirmRetry(prompts, 'Try again with different values?');
+    if (retry) {
+      return 'retry';
+    }
+  }
+  const saveAnyway = await prompts.confirm({
+    message: 'Save configuration anyway?',
+    default: false,
+  });
+  return saveAnyway ? 'save-anyway' : 'abort';
+}
+
+function readCurrentConfig(
+  registry: ConfigRegistry,
+  product: ProductDefinition,
+): ProductRuntimeConfig {
+  const pageSizeRaw = registry.resolve(product, 'defaultPageSize').value;
+  const pageSize = parsePositiveInteger(pageSizeRaw) ?? FALLBACK_PAGE_SIZE;
+  return {
+    host: registry.resolve(product, 'host').value,
+    apiBasePath: registry.resolve(product, 'apiBasePath').value,
+    token: registry.resolve(product, 'token').value,
+    defaultPageSize: pageSize,
+  };
+}
+
+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;
+}
+
 function requireHomeFile(registry: ConfigRegistry): HomeFileSource {
   const homeFile = registry.getWritableSource(
     (s): s is HomeFileSource => s instanceof HomeFileSource,
@@ -82,7 +310,7 @@ function printCurrent(
   log: (message: string) => void,
   registry: ConfigRegistry,
   product: ProductDefinition,
-  current: ReturnType<typeof getProductRuntimeConfig>,
+  current: ProductRuntimeConfig,
 ): void {
   const keys: ConfigKey[] = ['host', 'apiBasePath', 'token', 'defaultPageSize'];
   for (const key of keys) {
@@ -98,42 +326,93 @@ function printCurrent(
 async function promptForValues(
   prompts: SetupPrompts,
   product: ProductDefinition,
-  current: ReturnType<typeof getProductRuntimeConfig>,
+  defaults: PromptDefaults,
+  args: ParsedSetupArgs | undefined,
 ): Promise<PromptResult> {
-  const host = await prompts.input({
+  const host = args?.host ?? await prompts.input({
     message: 'Host (e.g. jira.example.com):',
-    default: current.host ?? '',
+    default: defaults.host ?? '',
+    validate: SetupValueValidator.host,
   });
-  const apiBasePath = await prompts.input({
+  const apiBasePath = args?.apiBasePath ?? await prompts.input({
     message: 'API base path:',
-    default: current.apiBasePath ?? product.defaultApiBasePath ?? '',
+    default: defaults.apiBasePath ?? product.defaultApiBasePath ?? '',
+    validate: SetupValueValidator.apiBasePath,
   });
-  const defaultPageSize = await prompts.input({
+  const defaultPageSize = args?.defaultPageSize ?? await prompts.input({
     message: 'Default page size:',
-    default: String(current.defaultPageSize ?? FALLBACK_PAGE_SIZE),
-    validate: (raw) =>
-      /^\d+$/.test(raw.trim()) && Number.parseInt(raw.trim(), 10) > 0
-        ? true
-        : 'Enter a positive integer',
+    default: String(defaults.defaultPageSize ?? FALLBACK_PAGE_SIZE),
+    validate: SetupValueValidator.pageSize,
   });
-  const token = await promptForToken(prompts, current.token);
-  return { host: host.trim(), apiBasePath: apiBasePath.trim(), defaultPageSize: defaultPageSize.trim(), token };
+  const token = await promptForToken(prompts, defaults.token, args?.token);
+  return {
+    host: host.trim(),
+    apiBasePath: apiBasePath.trim(),
+    defaultPageSize: defaultPageSize.trim(),
+    ...token,
+  };
 }
 
 async function promptForToken(
   prompts: SetupPrompts,
   existing: string | undefined,
-): Promise<string | undefined> {
-  const entered = await prompts.password({ message: 'API token:', mask: '*' });
+  fromArgs: string | undefined,
+): Promise<TokenPromptResult> {
+  if (fromArgs) {
+    return { tokenToWrite: fromArgs, tokenForValidation: fromArgs };
+  }
+  const entered = await prompts.password({
+    message: 'API token:',
+    mask: '*',
+    validate: SetupValueValidator.token,
+  });
   const trimmed = entered.trim();
   if (trimmed.length > 0) {
-    return trimmed;
+    return { tokenToWrite: trimmed, tokenForValidation: trimmed };
   }
   if (!existing) {
-    return undefined;
+    return { tokenToWrite: undefined, tokenForValidation: undefined };
   }
-  await prompts.confirm({ message: 'Keep existing token?', default: true });
-  return undefined;
+  const keepExisting = await prompts.confirm({ message: 'Keep existing token?', default: true });
+  return {
+    tokenToWrite: undefined,
+    tokenForValidation: keepExisting ? existing : undefined,
+  };
+}
+
+function validateAnswers(product: ProductDefinition, answers: PromptResult): string[] {
+  const errors: string[] = [];
+  for (const [label, value, validator] of [
+    ['host', answers.host, SetupValueValidator.host],
+    ['API base path', answers.apiBasePath, SetupValueValidator.apiBasePath],
+  ] as const) {
+    const result = validator(value);
+    if (result !== true) {
+      errors.push(`${label}: ${result}`);
+    }
+  }
+
+  const pageSize = SetupValueValidator.pageSize(answers.defaultPageSize);
+  if (pageSize !== true) {
+    errors.push(`default page size: ${pageSize}`);
+  }
+
+  if (!answers.tokenForValidation) {
+    errors.push(`API token is required (${product.envVars.token}).`);
+  } else {
+    const tokenResult = SetupValueValidator.token(answers.tokenForValidation);
+    if (tokenResult !== true) {
+      errors.push(`API token: ${tokenResult}`);
+    }
+  }
+
+  const hasHost = answers.host.length > 0;
+  const hasFullApiBasePath = /^https?:\/\//i.test(answers.apiBasePath);
+  if (!hasHost && !hasFullApiBasePath) {
+    errors.push(`Enter ${product.envVars.host}, or enter a full URL for ${product.envVars.apiBasePath}.`);
+  }
+
+  return errors;
 }
 
 function writeNonSecretFields(
@@ -208,7 +487,10 @@ async function tryWrite(
         message: 'Fall back to plaintext home file with mode 0600?',
         default: false,
       });
-      return !fallback;
+      if (fallback) {
+        return false;
+      }
+      throw new Error('Token was not saved because keychain write failed and plaintext fallback was declined');
     }
     return false;
   }
@@ -254,7 +536,7 @@ function printSummary(
   log(`  apiBasePath: ${answers.apiBasePath || '(unchanged)'}`);
   log(`  defaultPageSize: ${answers.defaultPageSize || '(unchanged)'}`);
   if (tokenWriter) {
-    log(`  token: ${maskToken(answers.token)} (stored in ${describeWriter(tokenWriter, product)})`);
+    log(`  token: ${maskToken(answers.tokenToWrite)} (stored in ${describeWriter(tokenWriter, product)})`);
   } else {
     log('  token: (unchanged)');
   }