feat: standardize error handling in CLI (#261)

Nithishvb · replexicabot · web-flow · commit 62c464d56029 · 2024-10-22T17:59:03.000-07:00
* feat: standardize error handling in CLI

* fix: changset file to ensure all CI/CD checks pass

---------

Co-authored-by: Replexica &lt;support@replexica.com&gt;
diff --git a/.changeset/tidy-pillows-greet.md b/.changeset/tidy-pillows-greet.md
@@ -0,0 +1,6 @@
+---
+"@replexica/cli": patch
+"replexica": patch
+---
+
+This pr introduces a custom error handling base class for the CLI
diff --git a/packages/cli/src/cli/i18n.ts b/packages/cli/src/cli/i18n.ts
@@ -10,6 +10,7 @@ import { createAuthenticator } from './../workers/auth';
 import { ReplexicaEngine } from '@replexica/sdk';
 import { expandPlaceholderedGlob, createBucketLoader } from '../workers/bucket';
 import { ensureLockfileExists } from './lockfile';
+import { ReplexicaCLIError } from '../utils/errors';
 
 export default new Command()
   .command('i18n')
@@ -34,13 +35,25 @@ export default new Command()
       const settings = await loadSettings(flags.apiKey);
 
       if (!i18nConfig) {
-        throw new Error('i18n.json not found. Please run `replexica init` to initialize the project.');
+        throw new ReplexicaCLIError({
+          message: 'i18n.json not found. Please run `replexica init` to initialize the project.',
+          docUrl: "i18nNotFound"
+        });
       } else if (!i18nConfig.buckets || !Object.keys(i18nConfig.buckets).length) {
-        throw new Error('No buckets found in i18n.json. Please add at least one bucket containing i18n content.');
+        throw new ReplexicaCLIError({
+          message: "No buckets found in i18n.json. Please add at least one bucket containing i18n content.",
+          docUrl: "bucketNotFound"
+        });
       } else if (flags.locale && !i18nConfig.locale.targets.includes(flags.locale)) {
-        throw new Error(`Source locale ${i18nConfig.locale.source} does not exist in i18n.json locale.targets. Please add it to the list and try again.`);
+        throw new ReplexicaCLIError({
+          message: `Source locale ${i18nConfig.locale.source} does not exist in i18n.json locale.targets. Please add it to the list and try again.`,
+          docUrl: "localeTargetNotFound"
+        });
       } else if (flags.bucket && !i18nConfig.buckets[flags.bucket]) {
-        throw new Error(`Bucket ${flags.bucket} does not exist in i18n.json. Please add it to the list and try again.`);
+        throw new ReplexicaCLIError({
+          message: `Bucket ${flags.bucket} does not exist in i18n.json. Please add it to the list and try again.`,
+          docUrl: "bucketNotFound"
+        });
       } else {
         ora.succeed('Replexica configuration loaded');
       }
@@ -50,7 +63,10 @@ export default new Command()
       try {
         lockfileResult = await ensureLockfileExists();
       } catch (error: any) {
-        throw new Error(`Failed to ensure lockfile exists: ${error.message}`);
+        throw new ReplexicaCLIError({
+          message: `Failed to ensure lockfile exists: ${error.message}`,
+          docUrl: "lockFiletNotFound"
+        });
       }
       if (lockfileResult === 'exists') {
         ora.succeed(`Lockfile exists`);
@@ -65,7 +81,10 @@ export default new Command()
       });
       const auth = await authenticator.whoami();
       if (!auth) {
-        throw new Error('Not authenticated');
+        throw new ReplexicaCLIError({
+          message: 'Not authenticated',
+          docUrl: "authError"
+        });
       }
 
       ora.start('Connecting to Replexica AI engine');
@@ -76,7 +95,10 @@ export default new Command()
           apiUrl: settings.auth.apiUrl,
         });
       } catch (error: any) {
-        throw new Error(`Failed to initialize ReplexicaEngine: ${error.message}`);
+        throw new ReplexicaCLIError({
+          message: `Failed to initialize ReplexicaEngine: ${error.message}`,
+          docUrl: "failedReplexicaEngine"
+        });
       }
       ora.succeed('Replexica AI engine connected');
 
@@ -102,7 +124,10 @@ export default new Command()
           }
         }
       } catch (error: any) {
-        throw new Error(`Failed to expand placeholdered globs: ${error.message}`);
+        throw new ReplexicaCLIError({
+          message: `Failed to expand placeholdered globs: ${error.message}`,
+          docUrl: "placeHolderFailed"
+        });
       }
 
       const lockfileProcessor = createLockfileProcessor();
@@ -164,7 +189,10 @@ export default new Command()
           };
 
           if (flags.frozen && (payloadStats.processable > 0 || payloadStats.deleted > 0)) {
-            throw new Error(`Translations are not up to date. Run the command without the --frozen flag to update the translations, then try again.`);
+            throw new ReplexicaCLIError({
+              message: `Translations are not up to date. Run the command without the --frozen flag to update the translations, then try again.`,
+              docUrl: "translationFailed"
+            });
           }
 
           let processedPayload: Record<string, string> = {};
diff --git a/packages/cli/src/cli/show/files.ts b/packages/cli/src/cli/show/files.ts
@@ -5,6 +5,7 @@ import Z from 'zod';
 import { loadConfig } from "../../workers/config";
 import { bucketTypeSchema } from "@replexica/spec";
 import { expandPlaceholderedGlob } from "../../workers/bucket";
+import { ReplexicaCLIError } from "../../utils/errors";
 
 export default new Command()
   .command("files")
@@ -16,7 +17,10 @@ export default new Command()
       const i18nConfig = await loadConfig();
 
       if (!i18nConfig) {
-        throw new Error('i18n.json not found. Please run `replexica init` to initialize the project.');
+        throw new ReplexicaCLIError({
+          message: 'i18n.json not found. Please run `replexica init` to initialize the project.',
+          docUrl: "i18nNotFound"
+        });
       }
 
       // Expand the placeholdered globs into actual (placeholdered) paths
@@ -38,7 +42,10 @@ export default new Command()
           }
         }
       } catch (error: any) {
-        throw new Error(`Failed to expand placeholdered globs: ${error.message}`);
+        throw new ReplexicaCLIError({
+          message: `Failed to expand placeholdered globs: ${error.message}`,
+          docUrl: "placeHolderFailed"
+        });
       }
 
       const files: string[] = [];
diff --git a/packages/cli/src/cli/show/locale.ts b/packages/cli/src/cli/show/locale.ts
@@ -3,6 +3,7 @@ import _ from "lodash";
 import Z from 'zod';
 import Ora from 'ora';
 import { localeCodes } from "@replexica/spec";
+import { ReplexicaCLIError } from "../../utils/errors";
 
 export default new Command()
   .command("locale")
@@ -14,7 +15,10 @@ export default new Command()
     const ora = Ora();
     try {
       switch (type) {
-        default: throw new Error(`Invalid type: ${type}`);
+        default: throw new ReplexicaCLIError({
+          message: `Invalid type: ${type}`,
+          docUrl: 'invalidType'
+        });
         case 'sources':
           localeCodes.forEach((locale) => console.log(locale));
           break;
diff --git a/packages/cli/src/utils/errors.ts b/packages/cli/src/utils/errors.ts
@@ -0,0 +1,28 @@
+export const docLinks = {
+  i18nNotFound: "https://docs.replexica.com/quickstart#initialization",
+  bucketNotFound: "https://docs.replexica.com/config#buckets",
+  authError: "https://docs.replexica.com/auth",
+  localeTargetNotFound: "https://docs.replexica.com/config#locale",
+  lockFiletNotFound: "https://docs.replexica.com/config#i18n-lock",
+  failedReplexicaEngine: "https://docs.replexica.com/",
+  placeHolderFailed: "https://docs.replexica.com/formats/json",
+  translationFailed: "https://docs.replexica.com/setup/cli#core-command-i18n",
+  connectionFailed: "https://docs.replexica.com/",
+  invalidType: "https://docs.replexica.com/setup/cli#configuration-commands",
+  invalidPathPattern: "https://docs.replexica.com/config#buckets",
+  androidResouceError: "https://docs.replexica.com/formats/android",
+  invalidBucketType: "https://docs.replexica.com/config#buckets",
+  invalidStringDict: "https://docs.replexica.com/formats/xcode-stringsdict",
+};
+
+type DocLinkKeys = keyof typeof docLinks;
+
+export class ReplexicaCLIError extends Error {
+  public readonly docUrl: string;
+
+  constructor({ message, docUrl }: { message: string; docUrl: DocLinkKeys }) {
+    super(message);
+    this.docUrl = docLinks[docUrl];
+    this.message = `${this.message}\n visit: ${this.docUrl}`;
+  }
+}
diff --git a/packages/cli/src/workers/auth.ts b/packages/cli/src/workers/auth.ts
@@ -1,3 +1,5 @@
+import { ReplexicaCLIError } from "../utils/errors";
+
 export type AuthenticatorParams = {
   apiUrl: string;
   apiKey: string;
@@ -32,7 +34,10 @@ export function createAuthenticator(params: AuthenticatorParams) {
       } catch (error) {
         const isNetworkError = error instanceof TypeError && error.message === "fetch failed";
         if (isNetworkError) {
-          throw new Error(`Failed to connect to the API at ${params.apiUrl}. Please check your connection and try again.`);
+          throw new ReplexicaCLIError({
+            message: `Failed to connect to the API at ${params.apiUrl}. Please check your connection and try again.`,
+            docUrl: "connectionFailed"
+          });
         } else {
           throw error;
         }
diff --git a/packages/cli/src/workers/bucket/android.ts b/packages/cli/src/workers/bucket/android.ts
@@ -1,5 +1,6 @@
 import { parseStringPromise, Builder } from 'xml2js';
 import { BucketLoader } from './_base';
+import { ReplexicaCLIError } from '../../utils/errors';
 
 interface AndroidResource {
   $: {
@@ -66,7 +67,10 @@ export const androidLoader = (): BucketLoader<string, Record<string, any>> => ({
       return result;
     } catch (error) {
       console.error('Error parsing Android resource file:', error);
-      throw new Error('Failed to parse Android resource file');
+      throw new ReplexicaCLIError({
+        message: 'Failed to parse Android resource file',
+        docUrl: "androidResouceError"
+      });
     }
   },
 
diff --git a/packages/cli/src/workers/bucket/index.ts b/packages/cli/src/workers/bucket/index.ts
@@ -16,24 +16,37 @@ import { propertiesLoader } from './properties';
 import { xcodeStringsLoader } from './xcode-strings';
 import { xcodeStringsdictLoader } from './xcode-stringsdict';
 import { flutterLoader } from './flutter';
+import { ReplexicaCLIError } from '../../utils/errors';
 
 // Path expansion
 export function expandPlaceholderedGlob(pathPattern: string, sourceLocale: string): string[] {
   // Throw if pathPattern is an absolute path
   if (path.isAbsolute(pathPattern)) {
-    throw new Error(`Invalid path pattern: ${pathPattern}. Path pattern must be relative.`);
+    throw new ReplexicaCLIError({
+      message: `Invalid path pattern: ${pathPattern}. Path pattern must be relative.`,
+      docUrl: 'invalidPathPattern'
+    });
   }
   // Throw if pathPattern points outside the current working directory
   if (path.relative(process.cwd(), pathPattern).startsWith('..')) {
-    throw new Error(`Invalid path pattern: ${pathPattern}. Path pattern must be within the current working directory.`);
+    throw new ReplexicaCLIError({
+      message: `Invalid path pattern: ${pathPattern}. Path pattern must be within the current working directory.`,
+      docUrl: "invalidPathPattern"
+    });
   }
   // Throw error if pathPattern contains "**" – we don't support recursive path patterns
   if (pathPattern.includes('**')) {
-    throw new Error(`Invalid path pattern: ${pathPattern}. Recursive path patterns are not supported.`);
+    throw new ReplexicaCLIError({
+      message: `Invalid path pattern: ${pathPattern}. Recursive path patterns are not supported.`,
+      docUrl: 'invalidPathPattern'
+    });
   }
   // Throw error if pathPattern contains "[locale]" several times
   if (pathPattern.split('[locale]').length > 2) {
-    throw new Error(`Invalid path pattern: ${pathPattern}. Path pattern must contain at most one "[locale]" placeholder.`);
+    throw new ReplexicaCLIError({
+      message: `Invalid path pattern: ${pathPattern}. Path pattern must contain at most one "[locale]" placeholder.`,
+      docUrl: "invalidPathPattern"
+    });
   }
   // Break down path pattern into parts
   const pathPatternChunks = pathPattern.split(path.sep);
@@ -77,7 +90,10 @@ export function createBucketLoader(params: CreateBucketLoaderParams) {
   const filepath = params.placeholderedPath.replace(/\[locale\]/g, params.locale);
   switch (params.bucketType) {
     default:
-      throw new Error(`Unsupported bucket type: ${params.bucketType}`);
+      throw new ReplexicaCLIError({
+        message: `Unsupported bucket type: ${params.bucketType}`,
+        docUrl: 'invalidBucketType'
+      });
     case 'markdown':
       return composeLoaders<string, Record<string, string>>(
         textLoader(filepath),
diff --git a/packages/cli/src/workers/bucket/xcode-stringsdict.ts b/packages/cli/src/workers/bucket/xcode-stringsdict.ts
@@ -1,16 +1,23 @@
 import plist from 'plist';
 import { BucketLoader } from './_base';
+import { ReplexicaCLIError } from '../../utils/errors';
 
 export const xcodeStringsdictLoader = (): BucketLoader<string, Record<string, any>> => ({
   async load(text: string) {
     try {
       const parsed = plist.parse(text);
       if (typeof parsed !== 'object' || parsed === null) {
-        throw new Error('Invalid .stringsdict format');
+        throw new ReplexicaCLIError({
+          message: 'Invalid .stringsdict format',
+          docUrl: "invalidStringDict"
+        });
       }
       return parsed as Record<string, any>;
     } catch (error: any) {
-      throw new Error(`Invalid .stringsdict format: ${error.message}`);
+      throw new ReplexicaCLIError({
+        message: `Invalid .stringsdict format: ${error.message}`,
+        docUrl: "invalidStringDict"
+      });
     }
   },
 
