feat(shell-api): add shell plugin feature

Author: addaleax

packages/shell-api/src/decorators.ts

@@ -12,7 +12,6 @@ import {
 import Help from './help';
 import { addHiddenDataProperty } from './helpers';
 import { checkInterrupted } from './interruptor';
-import { rephraseMongoError } from './mongo-errors';
 
 const addSourceToResultsSymbol = Symbol.for('@@mongosh.addSourceToResults');
 const resultSource = Symbol.for('@@mongosh.resultSource');
@@ -171,7 +170,7 @@ function wrapWithApiChecks<T extends(...args: any[]) => any>(fn: T, className: s
           fn.call(this, ...args)
         ]);
       } catch (e) {
-        throw rephraseMongoError(e);
+        throw internalState?.transformError(e) ?? e;
       } finally {
         if (interrupt) {
           interrupt.destroy();
@@ -187,7 +186,7 @@ function wrapWithApiChecks<T extends(...args: any[]) => any>(fn: T, className: s
       try {
         result = fn.call(this, ...args);
       } catch (e) {
-        throw rephraseMongoError(e);
+        throw internalState?.transformError(e) ?? e;
       }
       checkInterrupted(internalState);
       return result;

packages/shell-api/src/index.ts

@@ -5,7 +5,12 @@ import Database, { CollectionNamesWithTypes } from './database';
 import Explainable from './explainable';
 import ExplainableCursor from './explainable-cursor';
 import Help, { HelpProperties } from './help';
-import ShellInternalState, { EvaluationListener, ShellCliOptions, OnLoadResult } from './shell-internal-state';
+import ShellInternalState, {
+  EvaluationListener,
+  ShellCliOptions,
+  OnLoadResult,
+  ShellPlugin
+} from './shell-internal-state';
 import Shard from './shard';
 import ReplicaSet from './replica-set';
 import ShellApi from './shell-api';
@@ -62,5 +67,6 @@ export {
   ShellResult,
   ShellCliOptions,
   TypeSignature,
-  OnLoadResult
+  OnLoadResult,
+  ShellPlugin
 };

packages/shell-api/src/mongo-errors.ts

@@ -1,3 +1,4 @@
+import type { ShellPlugin } from './';
 
 interface MongoErrorRephrase {
   matchMessage?: RegExp | string;
@@ -37,3 +38,9 @@ export function rephraseMongoError(error: any): any {
 function isMongoError(error: any): boolean {
   return /^Mongo([A-Z].*)?Error$/.test(Object.getPrototypeOf(error)?.constructor?.name ?? '');
 }
+
+export class TransformMongoErrorPlugin implements ShellPlugin {
+  transformError(err: Error): Error {
+    return rephraseMongoError(err);
+  }
+}

packages/shell-api/src/shell-internal-state.ts

@@ -29,6 +29,7 @@ import {
 import { InterruptFlag } from './interruptor';
 import NoDatabase from './no-db';
 import constructShellBson from './shell-bson';
+import { TransformMongoErrorPlugin } from './mongo-errors';
 
 export interface ShellCliOptions {
   nodb?: boolean;
@@ -89,6 +90,10 @@ export interface EvaluationListener extends Partial<ConfigProvider<ShellUserConf
   startMongocryptd?: () => Promise<AutoEncryptionOptions['extraOptions']>;
 }
 
+export interface ShellPlugin {
+  transformError?: (err: Error) => Error;
+}
+
 /**
  * Anything to do with the internal shell state is stored here.
  */
@@ -114,6 +119,9 @@ export default class ShellInternalState {
     resume: (() => Promise<void>) | null
   }> | undefined;
 
+  private plugins: ShellPlugin[] = [ new TransformMongoErrorPlugin() ];
+  private alreadyTransformedErrors = new WeakMap<Error, Error>();
+
   constructor(initialServiceProvider: ServiceProvider, messageBus: any = new EventEmitter(), cliOptions: ShellCliOptions = {}) {
     this.initialServiceProvider = initialServiceProvider;
     this.messageBus = messageBus;
@@ -450,4 +458,26 @@ export default class ShellInternalState {
       serverType
     };
   }
+
+  registerPlugin(plugin: ShellPlugin): void {
+    this.plugins.push(plugin);
+  }
+
+  transformError(err: any): any {
+    if (Object.prototype.toString.call(err) === '[object Error]') {
+      if (this.alreadyTransformedErrors.has(err)) {
+        return this.alreadyTransformedErrors.get(err);
+      }
+      const before = err;
+
+      for (const plugin of this.plugins) {
+        if (plugin.transformError) {
+          err = plugin.transformError(err);
+        }
+      }
+
+      this.alreadyTransformedErrors.set(before, err);
+    }
+    return err;
+  }
 }

packages/snippet-manager/lib/index.d.ts

@@ -0,0 +1 @@
+export { SnippetManager } from './snippet-manager';

packages/snippet-manager/lib/index.js

@@ -0,0 +1,56 @@
+import { ShellPlugin, ShellInternalState } from '@mongosh/shell-api';
+import type { SnippetShellUserConfig, MongoshBus } from '@mongosh/types';
+export interface SnippetOptions {
+    installdir: string;
+    internalState: ShellInternalState;
+}
+export interface ErrorMatcher {
+    matches: RegExp[];
+    message: string;
+}
+export interface SnippetDescription {
+    name: string;
+    snippetName: string;
+    installSpec?: string;
+    version: string;
+    description: string;
+    license: string;
+    readme: string;
+    errorMatchers?: ErrorMatcher[];
+}
+export interface SnippetIndexFile {
+    indexFileVersion: 1;
+    index: SnippetDescription[];
+    metadata: {
+        homepage: string;
+    };
+    sourceURL: string;
+}
+export declare class SnippetManager implements ShellPlugin {
+    _internalState: ShellInternalState;
+    installdir: string;
+    repos: SnippetIndexFile[] | null;
+    load: (filename: string) => Promise<void>;
+    config: {
+        get<T extends keyof SnippetShellUserConfig>(key: T): Promise<SnippetShellUserConfig[T]>;
+    };
+    print: (...args: any[]) => Promise<void>;
+    npmArgv: string[];
+    inflightFetchIndexPromise: Promise<SnippetIndexFile[]> | null;
+    constructor({ installdir, internalState }: SnippetOptions);
+    get messageBus(): MongoshBus;
+    prepareNpm(): Promise<string[]>;
+    prepareIndex(refreshMode?: 'force-refresh' | 'allow-cached'): Promise<SnippetIndexFile[]>;
+    get snippets(): SnippetDescription[];
+    registryBaseUrl(): Promise<string>;
+    ensureSetup(): Promise<string[]>;
+    editPackageJSON<T>(fn: (pjson: any) => T): Promise<T>;
+    runNpm(...npmArgs: string[]): Promise<string>;
+    search(): Promise<string>;
+    loadAllSnippets(autoloadMode?: 'always' | 'only-autoload'): Promise<void>;
+    runSnippetCommand(args: string[]): Promise<string>;
+    runInstallLikeCmd(args: string[]): Promise<string>;
+    helpText(snippet?: string): Promise<string>;
+    showInfo(): Promise<string>;
+    transformError(err: Error): Error;
+}