i18nsmith 0.2.0 → 0.3.0

package/src/commands/check.ts

@@ -7,6 +7,13 @@ import type { CheckSummary } from '@i18nsmith/core';
 import { printLocaleDiffs } from '../utils/diff-utils.js';
 import { getDiagnosisExitSignal } from '../utils/diagnostics-exit.js';
 import { CHECK_EXIT_CODES } from '../utils/exit-codes.js';
+import {
+  runLocaleAudit,
+  printLocaleAuditResults,
+  hasAuditFindings,
+  type LocaleAuditSummary,
+} from '../utils/locale-audit.js';
+import { CliError, withErrorHandling } from '../utils/errors.js';
 
 interface CheckCommandOptions {
   config?: string;
@@ -24,6 +31,12 @@ interface CheckCommandOptions {
   diff?: boolean;
   invalidateCache?: boolean;
   preferDiagnosticsExit?: boolean;
+  audit?: boolean;
+  auditStrict?: boolean;
+  auditLocales?: string[];
+  auditDuplicates?: boolean;
+  auditInconsistent?: boolean;
+  auditOrphaned?: boolean;
 }
 
 const collectAssumedKeys = (value: string, previous: string[]) => {
@@ -114,78 +127,116 @@ export function registerCheck(program: Command) {
     .option('--invalidate-cache', 'Ignore cached sync analysis and rescan all source files', false)
     .option('--target <pattern...>', 'Limit translation reference scanning to specific files or patterns', collectTargetPatterns, [])
     .option('--prefer-diagnostics-exit', 'Prefer diagnostics exit codes when --fail-on=conflicts and blocking conflicts exist', false)
-    .action(async (options: CheckCommandOptions) => {
-      console.log(chalk.blue('Running guided repository health check...'));
-      try {
-        const { config, projectRoot, configPath } = await loadConfigWithMeta(options.config);
-        
-        // Inform user if config was found in a parent directory
-        const cwd = process.cwd();
-        if (projectRoot !== cwd) {
-          console.log(chalk.gray(`Config found at ${path.relative(cwd, configPath)}`));
-          console.log(chalk.gray(`Using project root: ${projectRoot}\n`));
-        }
-        
-        // Merge --assume-globs with config
-        if (options.assumeGlobs?.length) {
-          config.sync = config.sync ?? {};
-          config.sync.dynamicKeyGlobs = [
-            ...(config.sync.dynamicKeyGlobs ?? []),
-            ...options.assumeGlobs,
-          ];
-        }
-        const runner = new CheckRunner(config, { workspaceRoot: projectRoot });
-        const summary = await runner.run({
-          assumedKeys: options.assume,
-          validateInterpolations: options.validateInterpolations,
-          emptyValuePolicy: options.emptyValues === false ? 'fail' : undefined,
-          diff: options.diff,
-          targets: options.target,
-          invalidateCache: options.invalidateCache,
-        });
-
-        if (options.report) {
-          const outputPath = path.resolve(process.cwd(), options.report);
-          await fs.mkdir(path.dirname(outputPath), { recursive: true });
-          await fs.writeFile(outputPath, JSON.stringify(summary, null, 2));
-          console.log(chalk.green(`Health report written to ${outputPath}`));
-        }
+    .option('--audit', 'Include locale quality audit (duplicates, inconsistent keys, orphaned namespaces)', false)
+    .option('--audit-strict', 'Fail if locale audit finds issues (implies --audit)', false)
+  .option('--audit-locales <locales...>', 'Limit locale audit to specific locales (comma-separated)', collectTargetPatterns, [])
+  .option('--audit-duplicates', 'Include duplicate-value quality check during audit (defaults on when no other audit filters provided)', false)
+  .option('--audit-inconsistent', 'Include inconsistent-key quality check during audit', false)
+  .option('--audit-orphaned', 'Include orphaned-namespace quality check during audit', false)
+    .action(withErrorHandling(async (options: CheckCommandOptions) => runCheck(options)));
+}
 
-        if (options.json) {
-          console.log(JSON.stringify(summary, null, 2));
-        } else {
-          printCheckSummary(summary);
-          if (options.diff) {
-            printLocaleDiffs(summary.sync.diffs);
-          }
-        }
+export async function runCheck(options: CheckCommandOptions): Promise<void> {
+  const auditEnabled = Boolean(options.audit || options.auditStrict);
+  console.log(chalk.blue('Running guided repository health check...'));
+  try {
+    const { config, projectRoot, configPath } = await loadConfigWithMeta(options.config);
 
-        // If diagnostics discovered blocking conflicts, prefer the diagnostics' exit
-        // signal so CI can branch on specific failure modes (missing source locale,
-        // invalid JSON, etc.). This mirrors `i18nsmith diagnose` behavior.
-        // Only when --prefer-diagnostics-exit is true and --fail-on=conflicts.
-        const diagExit = getDiagnosisExitSignal(summary.diagnostics);
-        if (diagExit && options.preferDiagnosticsExit && options.failOn === 'conflicts') {
-          console.error(chalk.red(`\nBlocking diagnostic conflict detected: ${diagExit.reason}`));
-          console.error(chalk.red(`Exit code ${diagExit.code}`));
-          process.exitCode = diagExit.code;
-          return;
-        }
+    // Inform user if config was found in a parent directory
+    const cwd = process.cwd();
+    if (projectRoot !== cwd) {
+      console.log(chalk.gray(`Config found at ${path.relative(cwd, configPath)}`));
+      console.log(chalk.gray(`Using project root: ${projectRoot}\n`));
+    }
 
-        const failMode = (options.failOn ?? 'conflicts').toLowerCase();
-        const hasErrors = summary.actionableItems.some((item) => item.severity === 'error');
-        const hasWarnings = summary.actionableItems.some((item) => item.severity === 'warn');
+    // Merge --assume-globs with config
+    if (options.assumeGlobs?.length) {
+      config.sync = config.sync ?? {};
+      config.sync.dynamicKeyGlobs = [
+        ...(config.sync.dynamicKeyGlobs ?? []),
+        ...options.assumeGlobs,
+      ];
+    }
+    const runner = new CheckRunner(config, { workspaceRoot: projectRoot });
+    const summary = await runner.run({
+      assumedKeys: options.assume,
+      validateInterpolations: options.validateInterpolations,
+      emptyValuePolicy: options.emptyValues === false ? 'fail' : undefined,
+      diff: options.diff,
+      targets: options.target,
+      invalidateCache: options.invalidateCache,
+    });
 
-        if (failMode === 'conflicts' && hasErrors) {
-          console.error(chalk.red('\nBlocking issues detected. Resolve the actionable errors above.'));
-          process.exitCode = CHECK_EXIT_CODES.CONFLICTS;
-        } else if (failMode === 'warnings' && (hasErrors || hasWarnings)) {
-          console.error(chalk.red('\nWarnings detected. Use --fail-on conflicts to limit failures to blocking issues.'));
-          process.exitCode = CHECK_EXIT_CODES.WARNINGS;
+    let localeAudit: LocaleAuditSummary | undefined;
+    if (auditEnabled) {
+      const auditLocales = options.auditLocales?.filter(Boolean) ?? [];
+      const auditOverridesProvided = Boolean(options.auditDuplicates) || Boolean(options.auditInconsistent) || Boolean(options.auditOrphaned);
+
+      localeAudit = await runLocaleAudit(
+        { config, projectRoot },
+        {
+          locales: auditLocales.length ? auditLocales : undefined,
+          checkDuplicates: auditOverridesProvided ? Boolean(options.auditDuplicates) : true,
+          checkInconsistent: auditOverridesProvided ? Boolean(options.auditInconsistent) : true,
+          checkOrphaned: auditOverridesProvided ? Boolean(options.auditOrphaned) : true,
         }
-      } catch (error) {
-        console.error(chalk.red('Check failed:'), (error as Error).message);
-        process.exitCode = 1;
+      );
+    }
+
+    const payload = localeAudit ? { ...summary, audit: localeAudit } : summary;
+
+    if (options.report) {
+      const outputPath = path.resolve(process.cwd(), options.report);
+      await fs.mkdir(path.dirname(outputPath), { recursive: true });
+      await fs.writeFile(outputPath, JSON.stringify(payload, null, 2));
+      console.log(chalk.green(`Health report written to ${outputPath}`));
+    }
+
+    if (options.json) {
+      console.log(JSON.stringify(payload, null, 2));
+    } else {
+      printCheckSummary(summary);
+      if (options.diff) {
+        printLocaleDiffs(summary.sync.diffs);
       }
-    });
+      if (localeAudit) {
+        console.log(chalk.blue('\nLocale quality audit')); 
+        printLocaleAuditResults(localeAudit);
+      }
+    }
+
+    // Diagnostics exit override
+    const diagExit = getDiagnosisExitSignal(summary.diagnostics);
+    if (diagExit && options.preferDiagnosticsExit && (options.failOn ?? 'conflicts') === 'conflicts') {
+      console.error(chalk.red(`\nBlocking diagnostic conflict detected: ${diagExit.reason}`));
+      console.error(chalk.red(`Exit code ${diagExit.code}`));
+      process.exitCode = diagExit.code;
+      return;
+    }
+
+    const failMode = (options.failOn ?? 'conflicts').toLowerCase();
+    const hasErrors = summary.actionableItems.some((item) => item.severity === 'error');
+    const hasWarnings = summary.actionableItems.some((item) => item.severity === 'warn');
+    const auditHasIssues = Boolean(localeAudit && hasAuditFindings(localeAudit));
+
+    if (options.auditStrict && auditHasIssues) {
+      console.error(chalk.red('\nAudit detected locale quality issues (--audit-strict).'));
+      process.exitCode = CHECK_EXIT_CODES.WARNINGS;
+      return;
+    }
+
+    if (failMode === 'conflicts' && hasErrors) {
+      console.error(chalk.red('\nBlocking issues detected. Resolve the actionable errors above.'));
+      process.exitCode = CHECK_EXIT_CODES.CONFLICTS;
+    } else if (failMode === 'warnings' && (hasErrors || hasWarnings || auditHasIssues)) {
+      console.error(chalk.red('\nWarnings detected. Use --fail-on conflicts to limit failures to blocking issues.'));
+      process.exitCode = CHECK_EXIT_CODES.WARNINGS;
+    }
+  } catch (error) {
+    if (error instanceof CliError) {
+      throw error;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    throw new CliError(`Check failed: ${message}`);
+  }
 }

package/src/commands/config.ts

@@ -3,6 +3,7 @@ import path from 'path';
 import chalk from 'chalk';
 import type { Command } from 'commander';
 import { loadConfigWithMeta, DEFAULT_CONFIG_FILENAME } from '@i18nsmith/core';
+import { CliError, withErrorHandling } from '../utils/errors.js';
 
 interface ConfigCommandOptions {
   config?: string;
@@ -121,32 +122,33 @@ export function registerConfig(program: Command) {
     .description('Get a configuration value by key path (e.g., translationAdapter.module)')
     .option('-c, --config <path>', 'Path to i18nsmith config file', DEFAULT_CONFIG_FILENAME)
     .option('--json', 'Output as JSON', false)
-    .action(async (key: string, options: ConfigGetOptions) => {
-      try {
-        const { config, configPath } = await loadConfigWithMeta(options.config);
-        const keyPath = parseKeyPath(key);
-        const value = getNestedValue(config as unknown as Record<string, unknown>, keyPath);
+    .action(
+      withErrorHandling(async (key: string, options: ConfigGetOptions) => {
+        try {
+          const { config } = await loadConfigWithMeta(options.config);
+          const keyPath = parseKeyPath(key);
+          const value = getNestedValue(config as unknown as Record<string, unknown>, keyPath);
 
-        if (value === undefined) {
-          console.log(chalk.yellow(`Key "${key}" not found in config`));
-          process.exitCode = 1;
-          return;
-        }
+          if (value === undefined) {
+            throw new CliError(`Key "${key}" not found in config`);
+          }
 
-        if (options.json) {
-          console.log(JSON.stringify({ key, value }, null, 2));
-        } else {
-          if (typeof value === 'object' && value !== null) {
+          if (options.json) {
+            console.log(JSON.stringify({ key, value }, null, 2));
+          } else if (typeof value === 'object' && value !== null) {
             console.log(JSON.stringify(value, null, 2));
           } else {
             console.log(String(value));
           }
+        } catch (error) {
+          if (error instanceof CliError) {
+            throw error;
+          }
+          const message = error instanceof Error ? error.message : String(error);
+          throw new CliError(`Failed to get config: ${message}`);
         }
-      } catch (error) {
-        console.error(chalk.red('Failed to get config:'), (error as Error).message);
-        process.exitCode = 1;
-      }
-    });
+      })
+    );
 
   // Subcommand: config set <key> <value>
   configCmd
@@ -154,29 +156,34 @@ export function registerConfig(program: Command) {
     .description('Set a configuration value by key path (e.g., translationAdapter.module "src/i18n.ts")')
     .option('-c, --config <path>', 'Path to i18nsmith config file', DEFAULT_CONFIG_FILENAME)
     .option('--json', 'Output result as JSON', false)
-    .action(async (key: string, value: string, options: ConfigSetOptions) => {
-      try {
-        const { configPath } = await loadConfigWithMeta(options.config);
-        const { parsed } = await readRawConfig(configPath);
-        
-        const keyPath = parseKeyPath(key);
-        const parsedValue = parseValue(value);
-        
-        setNestedValue(parsed, keyPath, parsedValue);
-        
-        await writeConfig(configPath, parsed);
+    .action(
+      withErrorHandling(async (key: string, value: string, options: ConfigSetOptions) => {
+        try {
+          const { configPath } = await loadConfigWithMeta(options.config);
+          const { parsed } = await readRawConfig(configPath);
+
+          const keyPath = parseKeyPath(key);
+          const parsedValue = parseValue(value);
+
+          setNestedValue(parsed, keyPath, parsedValue);
 
-        if (options.json) {
-          console.log(JSON.stringify({ key, value: parsedValue, configPath }, null, 2));
-        } else {
-          console.log(chalk.green(`✓ Set ${key} = ${JSON.stringify(parsedValue)}`));
-          console.log(chalk.dim(`  Updated: ${configPath}`));
+          await writeConfig(configPath, parsed);
+
+          if (options.json) {
+            console.log(JSON.stringify({ key, value: parsedValue, configPath }, null, 2));
+          } else {
+            console.log(chalk.green(`✓ Set ${key} = ${JSON.stringify(parsedValue)}`));
+            console.log(chalk.dim(`  Updated: ${configPath}`));
+          }
+        } catch (error) {
+          if (error instanceof CliError) {
+            throw error;
+          }
+          const message = error instanceof Error ? error.message : String(error);
+          throw new CliError(`Failed to set config: ${message}`);
         }
-      } catch (error) {
-        console.error(chalk.red('Failed to set config:'), (error as Error).message);
-        process.exitCode = 1;
-      }
-    });
+      })
+    );
 
   // Subcommand: config list
   configCmd
@@ -184,37 +191,47 @@ export function registerConfig(program: Command) {
     .description('List all configuration values')
     .option('-c, --config <path>', 'Path to i18nsmith config file', DEFAULT_CONFIG_FILENAME)
     .option('--json', 'Output as JSON', false)
-    .action(async (options: ConfigCommandOptions) => {
-      try {
-        const { config, configPath } = await loadConfigWithMeta(options.config);
+    .action(
+      withErrorHandling(async (options: ConfigCommandOptions) => {
+        try {
+          const { config, configPath } = await loadConfigWithMeta(options.config);
 
-        if (options.json) {
-          console.log(JSON.stringify(config, null, 2));
-        } else {
-          console.log(chalk.blue(`Configuration from: ${configPath}`));
-          console.log();
-          console.log(JSON.stringify(config, null, 2));
+          if (options.json) {
+            console.log(JSON.stringify(config, null, 2));
+          } else {
+            console.log(chalk.blue(`Configuration from: ${configPath}`));
+            console.log();
+            console.log(JSON.stringify(config, null, 2));
+          }
+        } catch (error) {
+          if (error instanceof CliError) {
+            throw error;
+          }
+          const message = error instanceof Error ? error.message : String(error);
+          throw new CliError(`Failed to read config: ${message}`);
         }
-      } catch (error) {
-        console.error(chalk.red('Failed to read config:'), (error as Error).message);
-        process.exitCode = 1;
-      }
-    });
+      })
+    );
 
   // Subcommand: config path
   configCmd
     .command('path')
     .description('Print the path to the active config file')
     .option('-c, --config <path>', 'Path to i18nsmith config file', DEFAULT_CONFIG_FILENAME)
-    .action(async (options: ConfigCommandOptions) => {
-      try {
-        const { configPath } = await loadConfigWithMeta(options.config);
-        console.log(configPath);
-      } catch (error) {
-        console.error(chalk.red('Failed to find config:'), (error as Error).message);
-        process.exitCode = 1;
-      }
-    });
+    .action(
+      withErrorHandling(async (options: ConfigCommandOptions) => {
+        try {
+          const { configPath } = await loadConfigWithMeta(options.config);
+          console.log(configPath);
+        } catch (error) {
+          if (error instanceof CliError) {
+            throw error;
+          }
+          const message = error instanceof Error ? error.message : String(error);
+          throw new CliError(`Failed to find config: ${message}`);
+        }
+      })
+    );
 
   // Subcommand: config init-adapter <path>
   configCmd
@@ -223,41 +240,46 @@ export function registerConfig(program: Command) {
     .option('-c, --config <path>', 'Path to i18nsmith config file', DEFAULT_CONFIG_FILENAME)
     .option('--hook <name>', 'Name of the translation hook (default: useTranslation)', 'useTranslation')
     .option('--json', 'Output result as JSON', false)
-    .action(async (adapterPath: string, options: { config?: string; hook: string; json?: boolean }) => {
-      try {
-        const { configPath } = await loadConfigWithMeta(options.config);
-        const { parsed } = await readRawConfig(configPath);
+    .action(
+      withErrorHandling(async (adapterPath: string, options: { config?: string; hook: string; json?: boolean }) => {
+        try {
+          const { configPath } = await loadConfigWithMeta(options.config);
+          const { parsed } = await readRawConfig(configPath);
 
-        // Resolve relative path
-        const projectRoot = path.dirname(configPath);
-        const relativePath = path.isAbsolute(adapterPath)
-          ? path.relative(projectRoot, adapterPath)
-          : adapterPath;
+          // Resolve relative path
+          const projectRoot = path.dirname(configPath);
+          const relativePath = path.isAbsolute(adapterPath)
+            ? path.relative(projectRoot, adapterPath)
+            : adapterPath;
 
-        // Update translationAdapter
-        if (!parsed.translationAdapter || typeof parsed.translationAdapter !== 'object') {
-          parsed.translationAdapter = {};
-        }
-        const adapter = parsed.translationAdapter as Record<string, unknown>;
-        adapter.module = relativePath;
-        adapter.hookName = options.hook;
+          // Update translationAdapter
+          if (!parsed.translationAdapter || typeof parsed.translationAdapter !== 'object') {
+            parsed.translationAdapter = {};
+          }
+          const adapter = parsed.translationAdapter as Record<string, unknown>;
+          adapter.module = relativePath;
+          adapter.hookName = options.hook;
 
-        await writeConfig(configPath, parsed);
+          await writeConfig(configPath, parsed);
 
-        if (options.json) {
-          console.log(JSON.stringify({
-            translationAdapter: parsed.translationAdapter,
-            configPath,
-          }, null, 2));
-        } else {
-          console.log(chalk.green('✓ Translation adapter configured:'));
-          console.log(chalk.dim(`  module: ${relativePath}`));
-          console.log(chalk.dim(`  hookName: ${options.hook}`));
-          console.log(chalk.dim(`  Updated: ${configPath}`));
+          if (options.json) {
+            console.log(JSON.stringify({
+              translationAdapter: parsed.translationAdapter,
+              configPath,
+            }, null, 2));
+          } else {
+            console.log(chalk.green('✓ Translation adapter configured:'));
+            console.log(chalk.dim(`  module: ${relativePath}`));
+            console.log(chalk.dim(`  hookName: ${options.hook}`));
+            console.log(chalk.dim(`  Updated: ${configPath}`));
+          }
+        } catch (error) {
+          if (error instanceof CliError) {
+            throw error;
+          }
+          const message = error instanceof Error ? error.message : String(error);
+          throw new CliError(`Failed to configure adapter: ${message}`);
         }
-      } catch (error) {
-        console.error(chalk.red('Failed to configure adapter:'), (error as Error).message);
-        process.exitCode = 1;
-      }
-    });
+      })
+    );
 }

package/src/commands/debug-patterns.ts

@@ -3,6 +3,7 @@ import chalk from 'chalk';
 import { Command } from 'commander';
 import fg from 'fast-glob';
 import { loadConfigWithMeta } from '@i18nsmith/core';
+import { CliError, withErrorHandling } from '../utils/errors.js';
 
 interface DebugPatternsOptions {
   config?: string;
@@ -34,37 +35,39 @@ export function registerDebugPatterns(program: Command) {
     .option('-c, --config <path>', 'Path to i18nsmith config file', 'i18n.config.json')
     .option('--json', 'Print raw JSON results', false)
     .option('--verbose', 'Show all matched files for each pattern', false)
-    .action(async (options: DebugPatternsOptions) => {
-      try {
-        const { config, projectRoot, configPath } = await loadConfigWithMeta(options.config);
-        
-        console.log(chalk.blue('Debugging glob patterns...'));
-        console.log(chalk.gray(`Config: ${path.relative(process.cwd(), configPath)}`));
-        console.log(chalk.gray(`Project root: ${projectRoot}\n`));
+    .action(
+      withErrorHandling(async (options: DebugPatternsOptions) => {
+        try {
+          const { config, projectRoot, configPath } = await loadConfigWithMeta(options.config);
+          
+          console.log(chalk.blue('Debugging glob patterns...'));
+          console.log(chalk.gray(`Config: ${path.relative(process.cwd(), configPath)}`));
+          console.log(chalk.gray(`Project root: ${projectRoot}\n`));
 
-        const includePatterns = config.include ?? ['**/*.tsx', '**/*.ts', '**/*.jsx', '**/*.js'];
-        const excludePatterns = config.exclude ?? ['**/node_modules/**', '**/dist/**', '**/*.test.*', '**/*.spec.*'];
+          const includePatterns = config.include ?? ['**/*.tsx', '**/*.ts', '**/*.jsx', '**/*.js'];
+          const excludePatterns = config.exclude ?? ['**/node_modules/**', '**/dist/**', '**/*.test.*', '**/*.spec.*'];
 
-        const summary = await analyzePatterns(projectRoot, includePatterns, excludePatterns, options.verbose);
+          const summary = await analyzePatterns(projectRoot, includePatterns, excludePatterns, options.verbose);
 
-        if (options.json) {
-          console.log(JSON.stringify(summary, null, 2));
-          return;
-        }
+          if (options.json) {
+            console.log(JSON.stringify(summary, null, 2));
+            return;
+          }
 
-        printPatternAnalysis(summary, options.verbose);
-      } catch (error) {
-        console.error(chalk.red('Pattern debug failed:'), (error as Error).message);
-        process.exitCode = 1;
-      }
-    });
+          printPatternAnalysis(summary, options.verbose);
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          throw new CliError(`Pattern debug failed: ${message}`);
+        }
+      })
+    );
 }
 
 async function analyzePatterns(
   projectRoot: string,
   includePatterns: string[],
   excludePatterns: string[],
-  verbose?: boolean
+  _verbose?: boolean
 ): Promise<DebugPatternsSummary> {
   const includeMatches: PatternMatch[] = [];
   const excludeMatches: PatternMatch[] = [];
@@ -173,7 +176,7 @@ function generateSuggestions(
   return suggestions;
 }
 
-function suggestPatternFix(pattern: string, projectRoot: string): string | null {
+function suggestPatternFix(pattern: string, _projectRoot: string): string | null {
   // Common fixes for patterns that don't match
   
   // If pattern is like "src/**/*.tsx" but files are in "app/**/*.tsx"

package/src/commands/diagnose.ts

@@ -5,6 +5,7 @@ import type { Command } from 'commander';
 import { loadConfig, diagnoseWorkspace } from '@i18nsmith/core';
 import type { DiagnosisReport } from '@i18nsmith/core';
 import { getDiagnosisExitSignal } from '../utils/diagnostics-exit.js';
+import { CliError, withErrorHandling } from '../utils/errors.js';
 
 interface DiagnoseCommandOptions {
   config?: string;
@@ -103,34 +104,36 @@ export function registerDiagnose(program: Command) {
     .option('-c, --config <path>', 'Path to i18nsmith config file', 'i18n.config.json')
     .option('--json', 'Print raw JSON results', false)
     .option('--report <path>', 'Write JSON report to a file (for CI or editors)')
-    .action(async (options: DiagnoseCommandOptions) => {
-      console.log(chalk.blue('Running repository diagnostics...'));
-      try {
-        const config = await loadConfig(options.config);
-        const report = await diagnoseWorkspace(config);
+    .action(
+      withErrorHandling(async (options: DiagnoseCommandOptions) => {
+        console.log(chalk.blue('Running repository diagnostics...'));
+        try {
+          const config = await loadConfig(options.config);
+          const report = await diagnoseWorkspace(config);
 
-        if (options.report) {
-          const outputPath = path.resolve(process.cwd(), options.report);
-          await fs.mkdir(path.dirname(outputPath), { recursive: true });
-          await fs.writeFile(outputPath, JSON.stringify(report, null, 2));
-          console.log(chalk.green(`Diagnosis report written to ${outputPath}`));
-        }
+          if (options.report) {
+            const outputPath = path.resolve(process.cwd(), options.report);
+            await fs.mkdir(path.dirname(outputPath), { recursive: true });
+            await fs.writeFile(outputPath, JSON.stringify(report, null, 2));
+            console.log(chalk.green(`Diagnosis report written to ${outputPath}`));
+          }
 
-        if (options.json) {
-          console.log(JSON.stringify(report, null, 2));
-        } else {
-          printDiagnosisReport(report);
-        }
+          if (options.json) {
+            console.log(JSON.stringify(report, null, 2));
+          } else {
+            printDiagnosisReport(report);
+          }
 
-        const exitSignal = getDiagnosisExitSignal(report);
-        if (exitSignal) {
-          console.error(chalk.red(`\nBlocking conflicts detected (${report.conflicts.length}).`));
-          console.error(chalk.red(`Exit code ${exitSignal.code}: ${exitSignal.reason}`));
-          process.exitCode = exitSignal.code;
+          const exitSignal = getDiagnosisExitSignal(report);
+          if (exitSignal) {
+            console.error(chalk.red(`\nBlocking conflicts detected (${report.conflicts.length}).`));
+            console.error(chalk.red(`Exit code ${exitSignal.code}: ${exitSignal.reason}`));
+            process.exitCode = exitSignal.code;
+          }
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          throw new CliError(`Diagnose failed: ${message}`);
         }
-      } catch (error) {
-        console.error(chalk.red('Diagnose failed:'), (error as Error).message);
-        process.exitCode = 1;
-      }
-    });
+      })
+    );
 }