@metamask/snaps-cli 1.0.2 → 2.0.0

package/dist/types/errors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * An error that is thrown when the CLI fails. This is the base error for all
+ * CLI errors. It is not thrown directly, but is instead extended by other
+ * errors.
+ *
+ * This error is assumed to have all the information needed to display a
+ * readable error message, so it does not include the stack trace when it is
+ * thrown.
+ */
+export declare class CLIError extends Error {
+}
+/**
+ * An error that is thrown when a command fails.
+ *
+ * It wraps the error prefix in a bold red "Error" string.
+ */
+export declare class CommandError extends CLIError {
+    constructor(message: string, name?: string);
+}
+/**
+ * An error that is thrown when the config file cannot be loaded.
+ */
+export declare class ConfigError extends CommandError {
+    constructor(message: string);
+}

package/dist/types/index.d.ts

@@ -0,0 +1,5 @@
+export * as utils from './utils';
+export type { SnapConfig } from './config';
+export { getDefaultConfiguration, SnapsStatsPlugin, SnapsWatchPlugin, SnapsBuiltInResolver, SnapsBundleWarningsPlugin, } from './webpack';
+export type { SnapsStatsPluginOptions, SnapsWatchPluginOptions, SnapsBuiltInResolverOptions, SnapsBundleWarningsPluginOptions, } from './webpack';
+export { merge } from 'webpack-merge';

package/dist/types/utils/cli.d.ts

@@ -0,0 +1,17 @@
+export declare const CONFIG_FILE = "snap.config.js";
+export declare const TS_CONFIG_FILE = "snap.config.ts";
+/**
+ * Sanitizes inputs. Currently normalizes "./" paths to ".".
+ * Yargs handles other path normalization as specified in builders.
+ *
+ * @param argv - Arguments as an object generated by yargs.
+ */
+export declare function sanitizeInputs(argv: Record<string, unknown>): void;
+/**
+ * Trims leading and trailing periods "." and forward slashes "/" from the
+ * given path string.
+ *
+ * @param pathString - The path string to trim.
+ * @returns The trimmed path string.
+ */
+export declare function trimPathString(pathString: string): string;

package/dist/types/utils/errors.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Get the error message from an error in a Yargs `fail` handler. If the error
+ * is not `undefined`, {@link getErrorMessage} is used to get the error message.
+ * Otherwise, the given message is returned.
+ *
+ * @param message - The error message.
+ * @param error - The error object. This may be `undefined`.
+ * @returns The error message.
+ */
+export declare function getYargsErrorMessage(message: string, error?: unknown): string;
+/**
+ * Get the error message from an error.
+ *
+ * - If the error is an object with a `stack` property, the `stack` property is
+ * returned.
+ * - If the error is an object with a `message` property, the `message`
+ * property is returned.
+ * - Otherwise, the error is converted to a string and returned.
+ *
+ * @param error - The error to get the message from.
+ * @returns The error message.
+ */
+export declare function getErrorMessage(error: unknown): string;

package/dist/types/utils/index.d.ts

@@ -0,0 +1,6 @@
+export * from './cli';
+export * from './errors';
+export * from './legacy';
+export * from './logging';
+export * from './path';
+export * from './steps';

package/dist/types/utils/legacy.d.ts

@@ -0,0 +1,27 @@
+import type { LegacyOptions } from '../config';
+/**
+ * Get the dependencies to transpile, as well as the regular input file.
+ *
+ * If `transpilationMode` is not set to `localAndDeps`, this will return an
+ * empty array.
+ *
+ * @param config - The config object.
+ * @returns An array with regular expressions of dependencies that should be
+ * transpiled.
+ */
+export declare function processDependencies(config: LegacyOptions): RegExp[];
+/**
+ * Processes a string of space delimited dependencies into one RegExp string.
+ *
+ * @param dependencies - An array of dependencies to add to the RegExp.
+ * @returns A RegExp object.
+ */
+export declare function getDependencyRegExp(dependencies: string[]): RegExp | null;
+/**
+ * Helper function to remove any leading and trailing slashes from dependency
+ * list.
+ *
+ * @param dependencies - An array of dependencies to sanitize.
+ * @returns An array of sanitized paths.
+ */
+export declare function sanitizeDependencyPaths(dependencies: string[]): string[];

package/dist/types/utils/logging.d.ts

@@ -0,0 +1,22 @@
+import type { Ora } from 'ora';
+/**
+ * Log a warning message. The message is prefixed with "Warning:".
+ *
+ * @param message - The message to log.
+ * @param spinner - The spinner to clear.
+ */
+export declare function warn(message: string, spinner?: Ora): void;
+/**
+ * Log an info message.
+ *
+ * @param message - The message to log.
+ * @param spinner - The spinner to clear.
+ */
+export declare function info(message: string, spinner?: Ora): void;
+/**
+ * Log an error message. The message is prefixed with "Error:".
+ *
+ * @param message - The message to log.
+ * @param spinner - The spinner to clear.
+ */
+export declare function error(message: string, spinner?: Ora): void;

package/dist/types/utils/path.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Get the relative path from the current working directory to the given
+ * absolute path.
+ *
+ * @param absolutePath - The absolute path.
+ * @param cwd - The current working directory. Defaults to `process.cwd()`.
+ * @returns The relative path.
+ */
+export declare function getRelativePath(absolutePath: string, cwd?: string): string;

package/dist/types/utils/steps.d.ts

@@ -0,0 +1,17 @@
+import type { Ora } from 'ora';
+export declare type Step<Context extends Record<string, unknown>> = {
+    name: string;
+    condition?: (context: Context) => boolean;
+    task: (context: Context & {
+        spinner: Ora;
+    }) => Promise<void>;
+};
+export declare type Steps<Context extends Record<string, unknown>> = Readonly<Step<Context>[]>;
+/**
+ * Execute a list of steps in series. Each step receives the context object and
+ * a spinner instance.
+ *
+ * @param steps - The steps to execute.
+ * @param context - The context object that will be passed to each step.
+ */
+export declare function executeSteps<Context extends Record<string, unknown>>(steps: Steps<Context>, context: Context): Promise<void>;

package/dist/types/webpack/compiler.d.ts

@@ -0,0 +1,29 @@
+import type { Server } from 'http';
+import type { ProcessedConfig, ProcessedWebpackConfig } from '../config';
+import type { WebpackOptions } from './config';
+/**
+ * Get a Webpack compiler for the given config.
+ *
+ * @param config - The config object.
+ * @param options - The Webpack options.
+ * @returns The Webpack compiler.
+ */
+export declare function getCompiler(config: ProcessedWebpackConfig, options?: WebpackOptions): Promise<import("webpack").Compiler>;
+/**
+ * Get a static server for development purposes.
+ *
+ * Note: We're intentionally not using `webpack-dev-server` here because it
+ * adds a lot of extra stuff to the output that we don't need, and it's
+ * difficult to customize.
+ *
+ * @param config - The config object.
+ * @returns An object with a `listen` method that returns a promise that
+ * resolves when the server is listening.
+ */
+export declare function getServer(config: ProcessedConfig): {
+    listen: (port?: number) => Promise<{
+        port: number;
+        server: Server;
+        close: () => Promise<void>;
+    }>;
+};

package/dist/types/webpack/config.d.ts

@@ -0,0 +1,37 @@
+import type { Ora } from 'ora';
+import type { Configuration } from 'webpack';
+import type { ProcessedWebpackConfig } from '../config';
+export declare type WebpackOptions = {
+    /**
+     * Whether to watch for changes.
+     */
+    watch?: boolean;
+    /**
+     * Whether to evaluate the bundle. If this is set, it will override the
+     * `evaluate` option in the config object.
+     */
+    evaluate?: boolean;
+    /**
+     * The spinner to use for logging.
+     */
+    spinner?: Ora;
+};
+/**
+ * Get the default Webpack configuration. This is the configuration that will
+ * be used if the user doesn't provide a custom Webpack configuration. The
+ * configuration is based on the snap config.
+ *
+ * The default configuration includes:
+ *
+ * - `SWC` to transpile TypeScript and JavaScript files.
+ * - `TerserPlugin` to minify the bundle.
+ * - `SnapsWebpackPlugin` to validate the bundle and update the manifest.
+ *
+ * It can be customized through the `customizeWebpackConfig` function in the
+ * snap config, but in most cases, you shouldn't need to do that.
+ *
+ * @param config - The processed snap Webpack config.
+ * @param options - The Webpack options.
+ * @returns The default Webpack configuration.
+ */
+export declare function getDefaultConfiguration(config: ProcessedWebpackConfig, options?: WebpackOptions): Promise<Configuration>;

package/dist/types/webpack/index.d.ts

@@ -0,0 +1,3 @@
+export * from './compiler';
+export * from './config';
+export * from './plugins';

package/dist/types/webpack/loaders/browserify.d.ts

@@ -0,0 +1,16 @@
+import type { LoaderDefinitionFunction } from 'webpack';
+import type { LegacyOptions } from '../../config';
+/**
+ * A Browserify loader for Webpack. This exists for backwards compatibility with
+ * the legacy configuration format, in order to support the `bundlerCustomizer`
+ * function.
+ *
+ * When this loader is used, the input file will be processed by Browserify, and
+ * written to disk by Webpack. Most processing will be handled by Browserify, so
+ * there are no benefits like tree-shaking.
+ *
+ * @param content - The input file contents as a string.
+ * @param sourceMap - The source map of the input file.
+ */
+declare const loader: LoaderDefinitionFunction<LegacyOptions>;
+export default loader;

package/dist/types/webpack/loaders/wasm.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A Webpack loader that inlines the WASM module as a `Uint8Array`. This makes
+ * it possible to import the WASM module directly, and use it with the
+ * `WebAssembly.instantiate` function.
+ *
+ * This is useful, because snaps are not allowed to import assets from outside
+ * of their package. This loader allows you to inline the WASM module as a
+ * `Uint8Array`, which can then be passed to `WebAssembly.instantiate`.
+ *
+ * @param source - The WASM module as a string.
+ * @returns A string that exports the WASM module as a `Uint8Array`.
+ * @example
+ * ```ts
+ * import wasm from './program.wasm';
+ *
+ * const { instance } = await WebAssembly.instantiate(wasm, {});
+ * // Do something with the WASM module...
+ * ```
+ */
+export default function loader(source: unknown): string;

package/dist/types/webpack/plugins.d.ts

@@ -0,0 +1,147 @@
+import type { Ora } from 'ora';
+import type { Compiler, ResolvePluginInstance, Resolver, WebpackPluginInstance } from 'webpack';
+export declare type SnapsStatsPluginOptions = {
+    /**
+     * Whether to log the verbose stats.
+     */
+    verbose?: boolean;
+};
+/**
+ * A plugin that logs the stats after compilation. This is useful for logging
+ * the number of files compiled, and the time taken to compile them.
+ */
+export declare class SnapsStatsPlugin implements WebpackPluginInstance {
+    #private;
+    /**
+     * The options for the plugin.
+     */
+    readonly options: SnapsStatsPluginOptions;
+    constructor(options?: SnapsStatsPluginOptions, spinner?: Ora);
+    /**
+     * Apply the plugin to the Webpack compiler.
+     *
+     * @param compiler - The Webpack compiler.
+     */
+    apply(compiler: Compiler): void;
+}
+/**
+ * The options for the {@link SnapsWatchPlugin}.
+ */
+export declare type SnapsWatchPluginOptions = {
+    /**
+     * The bundle path. This is the file that will be evaluated, if the `evaluate`
+     * option is set.
+     */
+    bundle?: string;
+    /**
+     * Whether to evaluate the bundle. This only applies if the `bundle` option is
+     * set.
+     */
+    evaluate?: boolean;
+    /**
+     * The extra files to watch.
+     */
+    files?: string[];
+};
+/**
+ * A plugin that adds extra files to watch. This is useful for watching files
+ * that are not imported by the entry point, such as the `snap.manifest.json`
+ * file.
+ */
+export declare class SnapsWatchPlugin implements WebpackPluginInstance {
+    #private;
+    /**
+     * The options for the plugin.
+     */
+    readonly options: SnapsWatchPluginOptions;
+    constructor(options: SnapsWatchPluginOptions, spinner?: Ora);
+    /**
+     * Apply the plugin to the Webpack compiler.
+     *
+     * @param compiler - The Webpack compiler.
+     */
+    apply(compiler: Compiler): void;
+}
+/**
+ * The options for the {@link SnapsBuiltInResolver}.
+ */
+export declare type SnapsBuiltInResolverOptions = {
+    /**
+     * The built-in modules to ignore.
+     */
+    ignore?: string[];
+};
+/**
+ * A plugin that logs a message when a built-in module is not resolved. The
+ * MetaMask Snaps CLI does not support built-in modules by default, and this
+ * plugin is used to warn the user when they try to import a built-in module,
+ * when no fallback is configured.
+ */
+export declare class SnapsBuiltInResolver implements ResolvePluginInstance {
+    #private;
+    /**
+     * The built-in modules that have been imported, but not resolved.
+     */
+    readonly unresolvedModules: Set<string>;
+    /**
+     * The options for the plugin.
+     */
+    readonly options: SnapsBuiltInResolverOptions;
+    constructor(options?: SnapsBuiltInResolverOptions, spinner?: Ora);
+    /**
+     * Apply the plugin to the Webpack resolver.
+     *
+     * @param resolver - The Webpack resolver.
+     */
+    apply(resolver: Resolver): void;
+}
+/**
+ * The options for the {@link SnapsBundleWarningsPlugin}.
+ */
+export declare type SnapsBundleWarningsPluginOptions = {
+    /**
+     * The {@link SnapsBuiltInResolver} instance to use for detecting built-in
+     * modules.
+     */
+    builtInResolver?: SnapsBuiltInResolver | false;
+    /**
+     * Whether to show warnings if built-in modules are used, but not provided by
+     * Webpack's `fallback` configuration.
+     */
+    builtIns?: boolean;
+    /**
+     * Whether to show warnings if the `Buffer` global is used, but not provided
+     * by Webpack's `DefinePlugin`.
+     */
+    buffer?: boolean;
+};
+/**
+ * A plugin that logs a message when:
+ *
+ * - A built-in module is not resolved. The MetaMask Snaps CLI does not support
+ * built-in modules by default, and this plugin is used to warn the user when
+ * they try to import a built-in module, when no fallback is configured.
+ * - A snap uses the `Buffer` global. The MetaMask Snaps CLI does not support
+ * the `Buffer` global by default, and this plugin is used to warn the user when
+ * they try to use the `Buffer` global.
+ *
+ * We use both a resolver and a plugin, because the resolver is used to detect
+ * when a built-in module is imported, and the plugin is used to log a single
+ * message when the compilation is complete. We can't do everything in a single
+ * plugin, because the resolver doesn't have access to the compilation, and the
+ * plugin doesn't have access to the resolver.
+ */
+export declare class SnapsBundleWarningsPlugin implements WebpackPluginInstance {
+    #private;
+    /**
+     * The options for the plugin.
+     */
+    readonly options: SnapsBundleWarningsPluginOptions;
+    constructor(options?: SnapsBundleWarningsPluginOptions, spinner?: Ora);
+    /**
+     * Apply the plugin to the Webpack compiler.
+     *
+     * @param compiler - The Webpack compiler.
+     */
+    apply(compiler: Compiler): void;
+}

package/dist/types/webpack/utils.d.ts

@@ -0,0 +1,188 @@
+/// <reference types="browserify" />
+import type { Ora } from 'ora';
+import type { Configuration } from 'webpack';
+import type { ProcessedWebpackConfig } from '../config';
+export declare const BROWSERSLIST_FILE: string;
+export declare const WEBPACK_FALLBACKS: {
+    assert: string;
+    buffer: string;
+    console: string;
+    constants: string;
+    crypto: string;
+    domain: string;
+    events: string;
+    http: string;
+    https: string;
+    os: string;
+    path: string;
+    punycode: string;
+    process: string;
+    querystring: string;
+    stream: string;
+    _stream_duplex: string;
+    _stream_passthrough: string;
+    _stream_readable: string;
+    _stream_transform: string;
+    _stream_writable: string;
+    string_decoder: string;
+    sys: string;
+    timers: string;
+    tty: string;
+    url: string;
+    util: string;
+    vm: string;
+    zlib: string;
+};
+/**
+ * Get the default loader for JavaScript and TypeScript files, based on the
+ * config object.
+ *
+ * - If the `legacy` option is set, we use the custom `browserify` loader. This
+ * uses the legacy Browserify config to transpile the code.
+ * - Otherwise, we use the `swc-loader`. This is a Webpack loader that uses the
+ * `SWC` compiler, which is a much faster alternative to Babel and TypeScript's
+ * own compiler.
+ *
+ * @param config - The processed snap Webpack config.
+ * @param config.legacy - The legacy config object, if any.
+ * @param config.sourceMap - Whether to generate source maps.
+ * @see https://swc.rs/docs/usage/swc-loader
+ * @returns The default loader.
+ */
+export declare function getDefaultLoader({ legacy, sourceMap, }: ProcessedWebpackConfig): Promise<{
+    /**
+     * If the snap uses the legacy config, we use the custom `browserify`
+     * loader. This uses the legacy Browserify config to transpile the code.
+     * This is necessary for backwards compatibility with the
+     * `bundlerCustomizer` function.
+     */
+    loader: string;
+    /**
+     * The options for the `browserify` loader. These can be overridden in the
+     * snap config.
+     */
+    options: {
+        transpilationMode: import("../builders").TranspilationModes.LocalAndDeps;
+        depsToTranspile: string[];
+        writeManifest: boolean;
+        bundlerCustomizer?: ((bundler: import("browserify").BrowserifyObject) => void) | undefined;
+    } | {
+        transpilationMode: import("../builders").TranspilationModes.LocalOnly | import("../builders").TranspilationModes.None;
+        depsToTranspile: unknown[];
+        writeManifest: boolean;
+        bundlerCustomizer?: ((bundler: import("browserify").BrowserifyObject) => void) | undefined;
+    };
+} | {
+    /**
+     * We use the `swc-loader` to transpile TypeScript and JavaScript files.
+     * This is a Webpack loader that uses the `SWC` compiler, which is a much
+     * faster alternative to Babel and TypeScript's own compiler.
+     */
+    loader: string;
+    /**
+     * The options for the `swc-loader`. These can be overridden in the
+     * `.swcrc` file.
+     *
+     * @see https://swc.rs/docs/configuration/swcrc
+     */
+    options: {
+        sync: boolean;
+        /**
+         * This tells SWC to generate source maps. We set it to the
+         * `sourceMap` value from the config object.
+         *
+         * This must be enabled if source maps are enabled in the config.
+         */
+        sourceMaps: boolean;
+        jsc: {
+            parser: {
+                /**
+                 * This tells the parser to parse TypeScript files. If you
+                 * don't need to support TypeScript, you can set this to
+                 * `ecmascript` instead, but there's no harm in leaving it
+                 * as `typescript`.
+                 *
+                 * @see https://swc.rs/docs/configuration/compilation#jscparser
+                 */
+                syntax: string;
+            };
+        };
+        /**
+         * The module configuration. This tells SWC how to output the
+         * transpiled code.
+         *
+         * @see https://swc.rs/docs/configuration/modules
+         */
+        module: {
+            /**
+             * This tells SWC to output CommonJS modules. MetaMask Snaps
+             * doesn't support ES modules yet, so this is necessary.
+             *
+             * @see https://swc.rs/docs/configuration/modules#commonjs
+             */
+            type: string;
+        };
+        env: {
+            targets: string;
+        };
+    };
+}>;
+/**
+ * Get the Webpack devtool configuration based on the given snap config.
+ *
+ * - If `sourceMap` is `inline`, return `inline-source-map`.
+ * - If `sourceMap` is `true`, return `source-map`.
+ * - Otherwise, return `false`.
+ *
+ * @param sourceMap - The `sourceMap` value from the snap config.
+ * @returns The Webpack devtool configuration.
+ */
+export declare function getDevTool(sourceMap: ProcessedWebpackConfig['sourceMap']): Configuration['devtool'];
+/**
+ * Get a function that can be used as handler function for Webpack's
+ * `ProgressPlugin`.
+ *
+ * @param spinner - The spinner to update.
+ * @param spinnerText - The initial spinner text. This will be prepended to the
+ * percentage.
+ * @returns A function that can be used as handler function for Webpack's
+ * `ProgressPlugin`.
+ */
+export declare function getProgressHandler(spinner?: Ora, spinnerText?: string): (percentage: number) => void;
+/**
+ * Get the targets from the `.browserslistrc` file.
+ *
+ * @returns The browser targets as an array of strings.
+ */
+export declare function getBrowserslistTargets(): Promise<string[]>;
+/**
+ * Get a singular or plural string based on the given count. This is useful for
+ * generating messages like "1 error" or "2 errors". By default, the plural
+ * string is the singular string with an "s" appended to it.
+ *
+ * This assumes that the text is in English, and likely won't work for some
+ * other languages.
+ *
+ * @param count - The count.
+ * @param singular - The singular string.
+ * @param plural - The plural string.
+ * @returns The singular or plural string.
+ * @example
+ * ```typescript
+ * pluralize(1, 'error'); // => 'error'
+ * pluralize(2, 'error'); // => 'errors'
+ * pluralize(1, 'error', 'problem'); // => 'error'
+ * pluralize(2, 'error', 'problems'); // => 'problems'
+ * ```
+ */
+export declare function pluralize(count: number, singular: string, plural?: string): string;
+/**
+ * Get an object that can be used as fallback config for Webpack's
+ * `fallback` config.
+ *
+ * @param polyfills - The polyfill object from the snap config.
+ * @returns The webpack fallback config.
+ */
+export declare function getFallbacks(polyfills: ProcessedWebpackConfig['polyfills']): {
+    [index: string]: string | false;
+};