@bwat47/joplin-plugin-scripts 1.1.0 → 1.2.0

package/README.md

@@ -11,6 +11,7 @@ npm install -D @bwat47/joplin-plugin-scripts
 
 ```json
 "scripts": {
+    "typecheck": "tsc --noEmit",
     "dist": "npm run typecheck && joplin-plugin-scripts build",
     "updateVersion": "joplin-plugin-scripts update-version",
     "updateApi": "joplin-plugin-scripts update-api"
@@ -19,13 +20,13 @@ npm install -D @bwat47/joplin-plugin-scripts
 
 Commands run from the plugin project root, which npm scripts do automatically.
 
-| Command          | What it does                                                                                                                                     |
-| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `build`          | Validates the project, clears `dist/` and `publish/`, copies runtime assets from `src/`, bundles, and writes `publish/<id>.jpl` and `<id>.json`. |
-| `update-version` | Increments the patch version in `package.json`, `src/manifest.json`, and `package-lock.json` together, or writes nothing.                        |
-| `update-api`     | Replaces `api/` with the latest generator-joplin API and warns if the category or content-script external lists here differ.                     |
+| Command          | What it does                                                                                                                                                                           |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `build`          | Validates the project, clears `dist/` and `publish/`, copies runtime assets from `src/`, bundles, and writes `publish/<id>.jpl` and `<id>.json`.                                       |
+| `update-version` | Increments the patch version across `package.json`, `src/manifest.json`, and `package-lock.json`.                                                                                      |
+| `update-api`     | Replaces `api/` with the latest generator-joplin API and warns if the category or content-script external lists here differ. Requires npm, even when scripts run through Yarn or pnpm. |
 
-### Project layout expected
+### Expected project layout
 
 - `src/index.ts`: main entry point, bundled to `dist/index.js` for the Node platform.
   `node:` imports are rewritten to bare names for Joplin's plugin runtime.
@@ -41,7 +42,9 @@ Commands run from the plugin project root, which npm scripts do automatically.
 {
     "extraScripts": ["contentScripts/codeMirror.ts"],
     "webviewScripts": ["dialog/dialog.ts"],
-    "mainBuildOptions": { "external": ["jsdom"] }
+    "mainBuildOptions": { "external": ["jsdom"] },
+    "contentScriptBuildOptions": { "sourcemap": "inline" },
+    "webviewScriptBuildOptions": { "minify": false }
 }
 ```
 
@@ -50,13 +53,81 @@ Commands run from the plugin project root, which npm scripts do automatically.
   as CommonJS to the same path under `dist/` with a `.js` extension. Joplin's CodeMirror
   and Lezer packages stay external so they share the host's instances.
 - `webviewScripts`: scripts loaded into a dialog or panel with `addScript`, relative to
-  `src/`. A webview loads them as plain `<script>` tags with no `module`, `exports`, or
-  `require`, so each is bundled as a self-contained IIFE with nothing external. Exports
-  are dropped, so the script must start itself, e.g. by calling its init function at the
-  top level. Plain `.js` files in `src/` are copied as-is and don't need listing.
-- `mainBuildOptions`: esbuild options merged over the main bundle's defaults. Relative
-  `alias` targets resolve from the project root. `absWorkingDir`, `entryPoints`,
-  `outfile`, and `outdir` cannot be overridden.
+  `src/`. Each builds as a self-contained IIFE and must initialize itself. Plain `.js`
+  files in `src/` are copied automatically and don't need listing.
+
+Script output paths must be unique after normalization. They are compared without case on
+every platform, since the archive may be installed on a case-insensitive filesystem.
+`dist/index.js` is reserved for the main bundle. Invalid paths and collisions are rejected
+before existing build output is cleared.
+
+#### Advanced build options
+
+Each option group merges esbuild options over the defaults for its bundle type:
+
+| Option group                | Applies to           |
+| --------------------------- | -------------------- |
+| `mainBuildOptions`          | Main bundle only     |
+| `contentScriptBuildOptions` | Every content script |
+| `webviewScriptBuildOptions` | Every webview script |
+
+- Relative `alias` targets resolve from the project root.
+- `define` entries merge individually, preserving `process.env.NODE_ENV` as
+  `"production"` unless explicitly overridden.
+- Reserved options: `absWorkingDir`, `entryPoints`, `outfile`, `outdir`, `write`,
+  `format`, `plugins`, `bundle`, and `packages`. Content and webview scripts also
+  cannot override `platform`.
+- `external` keeps packages as runtime imports. Content-script entries extend the
+  CodeMirror and Lezer externals, which cannot be removed. Webview scripts cannot
+  set `external`, because they have no runtime `require`.
+- For debugging, prefer `"sourcemap": "inline"`. Setting it to `true` writes `.js.map`
+  files into `dist/` that ship in the `.jpl`.
+
+### Migrating from the standard Webpack setup
+
+#### Resolve the Joplin API through TypeScript paths
+
+Add these mappings to your existing `tsconfig.json` `compilerOptions` so `api` and
+`api/types` imports resolve for both TypeScript and esbuild:
+
+```json
+{
+    "compilerOptions": {
+        "paths": {
+            "api": ["./api/index.ts"],
+            "api/*": ["./api/*"]
+        }
+    }
+}
+```
+
+Remove `baseUrl` ([deprecated in TypeScript 6](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-6-0.html#deprecated---baseurl))
+and make all path targets relative to the declaring `tsconfig.json`. Add explicit
+mappings for any other imports that relied on `baseUrl`.
+
+#### Run type checking separately
+
+esbuild does not check types. Keep `tsc --noEmit` before the build, as shown in Usage.
+
+#### Translate Webpack overrides to esbuild options
+
+`webpackOverrides` is not supported. Replace it in `plugin.config.json` with
+equivalent esbuild options:
+
+| Webpack setting         | esbuild equivalent                                     |
+| ----------------------- | ------------------------------------------------------ |
+| `resolve.alias`         | `mainBuildOptions.alias`, or suitable tsconfig `paths` |
+| `devtool`               | `mainBuildOptions.sourcemap`                           |
+| `optimization.minimize` | `mainBuildOptions.minify`                              |
+| `externals`             | `mainBuildOptions.external`, using esbuild's syntax    |
+| Loaders and plugins     | Require an equivalent approach; they cannot be reused  |
+
+External dependencies remain runtime imports and must be available in Joplin's
+plugin runtime; marking a package external does not include it in the archive.
+
+The standard setup applies `webpackOverrides` to both main and content-script
+builds. Here, `mainBuildOptions` affects only the main bundle. Move settings that
+should also apply to content scripts into `contentScriptBuildOptions`.
 
 ### Testing a plugin's bundles
 
@@ -64,18 +135,21 @@ The package exports the same esbuild options the build uses, so plugin tests can
 in memory and run the result:
 
 ```js
-import { createBuildOptions, createContentScriptBuildOptions, readPluginConfig } from '@bwat47/joplin-plugin-scripts';
+import { createBuildOptions, readPluginConfig } from '@bwat47/joplin-plugin-scripts';
+import { build } from 'esbuild';
 
 const { mainBuildOptions } = await readPluginConfig(root);
 const result = await build({ ...createBuildOptions(root, mainBuildOptions), write: false });
 ```
 
-`createWebviewScriptBuildOptions` and `contentScriptExternals` are also exported.
+Also exported: `createContentScriptBuildOptions`, `createWebviewScriptBuildOptions`,
+`contentScriptExternals`, and `PluginScriptsError` for expected configuration and validation errors.
 
 ## Development
 
 ```sh
 npm test
+npm run typecheck
 npm run lint
 npm run format
 ```
@@ -83,5 +157,5 @@ npm run format
 To try a change in a plugin before publishing, run `npm pack` here and
 `npm install -D ../joplin-plugin-scripts/bwat47-joplin-plugin-scripts-<version>.tgz` in the plugin.
 
-Release: bump `version`, then `npm publish --access public` (`prepublishOnly` runs lint,
-format check, and tests).
+Release: bump `version`, then `npm publish --access public` (`prepublishOnly` runs type checking,
+lint, format check, and tests; `prepack` then generates the declarations).

package/bin/joplin-plugin-scripts.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { buildPlugin } from '../lib/build.mjs';
+import { PluginScriptsError } from '../lib/errors.mjs';
 import { updateApi } from '../lib/updateApi.mjs';
 import { updateVersion } from '../lib/updateVersion.mjs';
 
@@ -12,6 +13,7 @@ Commands:
   update-version  Increment the patch version in package.json, src/manifest.json, and package-lock.json
   update-api      Replace api/ with the declarations from the latest generator-joplin`;
 
+/** @type {Record<string, (root: string) => Promise<void>>} */
 const commands = {
     build: async (root) => {
         await buildPlugin(root);
@@ -36,5 +38,11 @@ if (!run || rest.length > 0) {
     console.error(USAGE);
     process.exit(1);
 }
-// Unhandled rejections print the stack and exit non-zero, as the original scripts did.
-await run(process.cwd());
+try {
+    await run(process.cwd());
+} catch (error) {
+    // Expected failures print only their message; anything else is a bug, so its stack is shown.
+    if (!(error instanceof PluginScriptsError)) throw error;
+    console.error(`Error: ${error.message}`);
+    process.exitCode = 1;
+}

package/lib/build.mjs

@@ -10,21 +10,24 @@ import {
     readPluginConfig,
     scriptOutputPaths,
 } from './buildConfig.mjs';
+import { PluginScriptsError } from './errors.mjs';
 import { packagePlugin, readProject } from './packagePlugin.mjs';
 
 /**
  * Builds the plugin at `root`: validates the project, clears `dist/` and `publish/`, copies runtime
  * assets from `src/`, bundles the main entry point, extra scripts, and webview scripts, and creates
  * the `.jpl` archive.
+ * @param {string} root Plugin project root.
  */
 export async function buildPlugin(root) {
     const dist = path.join(root, 'dist');
     const publish = path.join(root, 'publish');
     const { manifest } = await readProject(root);
-    const { extraScripts, webviewScripts, mainBuildOptions } = await readPluginConfig(root);
+    const { extraScripts, webviewScripts, mainBuildOptions, contentScriptBuildOptions, webviewScriptBuildOptions } =
+        await readPluginConfig(root);
     const scriptBuilds = [
-        ...extraScripts.map((script) => createContentScriptBuildOptions(root, script)),
-        ...webviewScripts.map((script) => createWebviewScriptBuildOptions(root, script)),
+        ...extraScripts.map((script) => createContentScriptBuildOptions(root, script, contentScriptBuildOptions)),
+        ...webviewScripts.map((script) => createWebviewScriptBuildOptions(root, script, webviewScriptBuildOptions)),
     ];
 
     // Only these fixed, project-local output directories are removed.
@@ -37,10 +40,27 @@ export async function buildPlugin(root) {
         recursive: true,
         filter: (source) => isRuntimeAsset(root, source),
     });
-    await Promise.all([
+    // Wait for every bundle, so esbuild has printed all of its errors before the build stops.
+    const results = await Promise.allSettled([
         build(createBuildOptions(root, mainBuildOptions)),
         ...scriptBuilds.map((options) => build(options)),
     ]);
+    const failures = results.filter((result) => result.status === 'rejected').map((result) => result.reason);
+    if (failures.length > 0) {
+        // esbuild's own failures carry `errors` and have already been logged; anything else is unexpected.
+        const unexpected = failures.find((failure) => !isEsbuildFailure(failure));
+        if (unexpected) throw unexpected;
+        throw new PluginScriptsError('Bundling failed; see the esbuild errors above.', { cause: failures[0] });
+    }
 
     await packagePlugin(root, manifest, scriptOutputPaths(extraScripts, webviewScripts));
 }
+
+/**
+ * Checks whether a rejected build is an esbuild `BuildFailure`, whose messages esbuild has already logged.
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+function isEsbuildFailure(error) {
+    return error instanceof Error && 'errors' in error && Array.isArray(error.errors);
+}

package/lib/buildConfig.mjs

@@ -1,6 +1,8 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 
+import { errorMessage, hasErrorCode, PluginScriptsError } from './errors.mjs';
+
 /** Name of the optional per-plugin build configuration file at the project root. */
 export const CONFIG_FILE = 'plugin.config.json';
 
@@ -22,10 +24,56 @@ const TEST_FILE_PATTERN = /\.(?:test|spec)\.[cm]?[jt]sx?$/;
 /** Matches a Node built-in import with the `node:` prefix, e.g. `node:path`. */
 const NODE_PREFIX_PATTERN = /^node:/;
 
-/** esbuild options that the package owns and `mainBuildOptions` may not override. */
-const RESERVED_BUILD_OPTIONS = ['absWorkingDir', 'entryPoints', 'outfile', 'outdir'];
+/**
+ * esbuild options that the package owns and no override may set: the input and output locations,
+ * `write` (packaging needs `dist/index.js` on disk), `format` (Joplin loads the main bundle as
+ * CommonJS), `plugins` (replacing them drops the `node:` prefix rewrite), and `bundle` and
+ * `packages`. Each output is loaded as a single file: with `bundle: false` or
+ * `packages: "external"`, its imports would stay as `require` calls for modules that are not in
+ * the archive or, in a webview, for a `require` that does not exist. Individual packages can
+ * still be made external with `external`.
+ */
+const RESERVED_BUILD_OPTIONS = [
+    'absWorkingDir',
+    'entryPoints',
+    'outfile',
+    'outdir',
+    'write',
+    'format',
+    'plugins',
+    'bundle',
+    'packages',
+];
+
+/**
+ * Further options that content-script and webview-script overrides may not set. Both kinds of
+ * script run in a webview, so `platform` stays `browser`: under `node`, a Node built-in import
+ * would become a `require` that fails at runtime instead of failing the build.
+ */
+const RESERVED_SCRIPT_BUILD_OPTIONS = [...RESERVED_BUILD_OPTIONS, 'platform'];
+
+/**
+ * Webview scripts also may not set `external`: an IIFE loaded by a `<script>` tag has no
+ * `require`, so any external import would fail at runtime.
+ */
+const RESERVED_WEBVIEW_BUILD_OPTIONS = [...RESERVED_SCRIPT_BUILD_OPTIONS, 'external'];
+
+/**
+ * Configuration keys holding esbuild overrides, with the options each may not set.
+ * @type {Record<'mainBuildOptions' | 'contentScriptBuildOptions' | 'webviewScriptBuildOptions', string[]>}
+ */
+const BUILD_OPTION_KEYS = {
+    mainBuildOptions: RESERVED_BUILD_OPTIONS,
+    contentScriptBuildOptions: RESERVED_SCRIPT_BUILD_OPTIONS,
+    webviewScriptBuildOptions: RESERVED_WEBVIEW_BUILD_OPTIONS,
+};
 
-/** Excludes bundled sources, tests, and development fixtures in `<root>/src` from copied runtime assets. */
+/**
+ * Excludes bundled sources, tests, and development fixtures in `<root>/src` from copied runtime assets.
+ * @param {string} root Plugin project root.
+ * @param {string} source
+ * @returns {boolean}
+ */
 export function isRuntimeAsset(root, source) {
     const parts = path.relative(path.join(root, 'src'), source).split(PATH_SEPARATOR_PATTERN);
     return (
@@ -73,6 +121,7 @@ const stripNodePrefix = {
  * Options shared by the main plugin and content-script bundles.
  * `api` resolves through tsconfig.json `paths`: api/index.ts exports Joplin's injected global,
  * and api/types contains runtime enums, so both are bundled.
+ * @param {string} root Plugin project root.
  * @returns {import('esbuild').BuildOptions}
  */
 function sharedOptions(root) {
@@ -92,43 +141,72 @@ function sharedOptions(root) {
 /**
  * Returns the esbuild options for the main plugin bundle, `src/index.ts` to `dist/index.js`.
  * `mainBuildOptions` from the plugin config are merged over the defaults.
+ * `define` entries are merged individually so unrelated definitions preserve the defaults.
  * @param {string} root Plugin project root.
  * @param {import('esbuild').BuildOptions} [overrides] The plugin config's `mainBuildOptions`.
  * @returns {import('esbuild').BuildOptions}
  */
 export function createBuildOptions(root, overrides = {}) {
+    const defaults = sharedOptions(root);
     return {
-        ...sharedOptions(root),
+        ...defaults,
         entryPoints: ['src/index.ts'],
         outfile: 'dist/index.js',
         platform: 'node',
         plugins: [stripNodePrefix],
         ...overrides,
+        define: { ...defaults.define, ...overrides.define },
     };
 }
 
 /**
- * Returns the esbuild options for one content script, e.g. `contentScripts/codeMirror.ts`
- * (relative to `src/`) to `dist/contentScripts/codeMirror.js`.
- * @param {string} root Plugin project root.
+ * Rejects a script path that is not a bundleable script inside `src/`, e.g. `../a.ts` or `notes.txt`.
  * @param {string} script Script path relative to `src/`.
- * @returns {import('esbuild').BuildOptions}
  */
-export function createContentScriptBuildOptions(root, script) {
+function assertValidScriptPath(script) {
     if (
         !SCRIPT_EXTENSION_PATTERN.test(script) ||
         path.isAbsolute(script) ||
         script.split(PATH_SEPARATOR_PATTERN).includes('..')
     ) {
-        throw new Error(`Invalid extra script path: ${script}`);
+        throw new PluginScriptsError(`Invalid extra script path: ${script}`);
     }
-    // Content scripts run in the editor webview, so they use esbuild's default browser platform:
-    // a Node built-in import fails the build instead of becoming a runtime require.
+}
+
+/**
+ * Options shared by content-script and webview-script bundles, with `overrides` merged over them.
+ * Scripts run in a webview, so they use esbuild's default browser platform: a Node built-in
+ * import fails the build instead of becoming a runtime require.
+ * @param {string} root Plugin project root.
+ * @param {string} script Script path relative to `src/`.
+ * @param {import('esbuild').BuildOptions} overrides
+ * @returns {import('esbuild').BuildOptions}
+ */
+function scriptOptions(root, script, overrides) {
+    assertValidScriptPath(script);
+    const defaults = sharedOptions(root);
     return {
-        ...sharedOptions(root),
+        ...defaults,
         entryPoints: [`src/${script}`],
         outfile: `dist/${script.replace(SCRIPT_EXTENSION_PATTERN, '.js')}`,
-        external: contentScriptExternals,
+        ...overrides,
+        define: { ...defaults.define, ...overrides.define },
+    };
+}
+
+/**
+ * Returns the esbuild options for one content script, e.g. `contentScripts/codeMirror.ts`
+ * (relative to `src/`) to `dist/contentScripts/codeMirror.js`. `overrides` are merged over the
+ * defaults; their `external` entries are added to the host libraries, which always stay external.
+ * @param {string} root Plugin project root.
+ * @param {string} script Script path relative to `src/`.
+ * @param {import('esbuild').BuildOptions} [overrides] The plugin config's `contentScriptBuildOptions`.
+ * @returns {import('esbuild').BuildOptions}
+ */
+export function createContentScriptBuildOptions(root, script, overrides = {}) {
+    return {
+        ...scriptOptions(root, script, overrides),
+        external: [...new Set([...contentScriptExternals, ...(overrides.external ?? [])])],
     };
 }
 
@@ -139,34 +217,151 @@ export function createContentScriptBuildOptions(root, script) {
  * self-contained IIFE. Their exports are dropped; the script runs for its side effects.
  * @param {string} root Plugin project root.
  * @param {string} script Script path relative to `src/`.
+ * @param {import('esbuild').BuildOptions} [overrides] The plugin config's `webviewScriptBuildOptions`.
  * @returns {import('esbuild').BuildOptions}
  */
-export function createWebviewScriptBuildOptions(root, script) {
+export function createWebviewScriptBuildOptions(root, script, overrides = {}) {
     return {
-        ...createContentScriptBuildOptions(root, script),
+        ...scriptOptions(root, script, overrides),
         format: 'iife',
         // A webview has no host CodeMirror instance to share, so everything is bundled.
         external: [],
     };
 }
 
-/** Returns `dist/`-relative output paths for every script the plugin config registers. */
+/**
+ * Returns `dist/`-relative output paths for every script the plugin config registers.
+ * @param {string[]} extraScripts Content-script paths relative to `src/`.
+ * @param {string[]} webviewScripts Webview-script paths relative to `src/`.
+ * @returns {string[]} Bundle paths relative to `dist/`, using native separators.
+ */
 export function scriptOutputPaths(extraScripts, webviewScripts) {
-    return [...extraScripts, ...webviewScripts].map((script) => script.replace(SCRIPT_EXTENSION_PATTERN, '.js'));
+    return [...extraScripts, ...webviewScripts].map((script) =>
+        path.normalize(script.replace(SCRIPT_EXTENSION_PATTERN, '.js'))
+    );
+}
+
+/**
+ * Shows a `dist/`-relative output path with `/` separators on every platform, e.g. `scripts\a.js` as `scripts/a.js`.
+ * @param {string} output Bundle path relative to `dist/`.
+ * @returns {string}
+ */
+function displayOutputPath(output) {
+    return output.replaceAll('\\', '/');
+}
+
+/**
+ * Output paths are compared without case on every platform: the archive may be installed on a
+ * case-insensitive filesystem (Windows, macOS), where `Editor.js` and `editor.js` are one file.
+ * @param {string} output Bundle path relative to `dist/`.
+ * @returns {string}
+ */
+function outputPathKey(output) {
+    return displayOutputPath(output).toLowerCase();
 }
 
+/**
+ * Checks whether a configuration value is an array of strings.
+ * @param {unknown} value
+ * @returns {value is string[]}
+ */
 function isStringArray(value) {
     return Array.isArray(value) && value.every((item) => typeof item === 'string');
 }
 
+/**
+ * Rejects a configuration entry that is not an array of script paths.
+ * @param {unknown} value
+ * @param {string} key
+ * @param {string} configPath
+ * @returns {asserts value is string[]}
+ */
+function assertScriptArray(value, key, configPath) {
+    if (!isStringArray(value)) {
+        throw new PluginScriptsError(`${configPath} "${key}" must be an array of paths relative to src/.`);
+    }
+}
+
+/**
+ * Checks whether a configuration value is a non-null, non-array object.
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
+/**
+ * Rejects malformed script paths, scripts that build to the main bundle's `dist/index.js`,
+ * and scripts that build to the same output path.
+ * @param {string} configPath Configuration file path used in error messages.
+ * @param {string[]} extraScripts Content-script paths relative to `src/`.
+ * @param {string[]} webviewScripts Webview-script paths relative to `src/`.
+ */
+function assertValidScripts(configPath, extraScripts, webviewScripts) {
+    // Report a malformed path as such, before normalization can make it look like a collision.
+    for (const script of [...extraScripts, ...webviewScripts]) assertValidScriptPath(script);
+    const mainOutput = outputPathKey('index.js');
+    const seen = new Set();
+    for (const output of scriptOutputPaths(extraScripts, webviewScripts)) {
+        const key = outputPathKey(output);
+        if (key === mainOutput) {
+            throw new PluginScriptsError(
+                `${configPath} lists a script that builds to dist/index.js, which is reserved for the main bundle.`
+            );
+        }
+        if (seen.has(key)) {
+            throw new PluginScriptsError(
+                `${configPath} lists more than one script that builds to dist/${displayOutputPath(output)}.`
+            );
+        }
+        seen.add(key);
+    }
+}
+
+/**
+ * Rejects build overrides that are not an object, set an option the package owns, or have
+ * `define` or `external` values the build cannot merge with its defaults.
+ * @param {unknown} options
+ * @param {keyof typeof BUILD_OPTION_KEYS} key
+ * @param {string} configPath
+ * @returns {asserts options is import('esbuild').BuildOptions}
+ */
+function assertBuildOptions(options, key, configPath) {
+    if (!isPlainObject(options)) {
+        throw new PluginScriptsError(`${configPath} "${key}" must be an object of esbuild options.`);
+    }
+    const reserved = BUILD_OPTION_KEYS[key].filter((option) => option in options);
+    if (reserved.length > 0) {
+        throw new PluginScriptsError(`${configPath} "${key}" cannot set ${reserved.join(', ')}.`);
+    }
+    const { define, external } = options;
+    if (
+        define !== undefined &&
+        !(isPlainObject(define) && Object.values(define).every((value) => typeof value === 'string'))
+    ) {
+        throw new PluginScriptsError(`${configPath} "${key}.define" must be an object of string replacements.`);
+    }
+    if (external !== undefined && !isStringArray(external)) {
+        throw new PluginScriptsError(`${configPath} "${key}.external" must be an array of module names.`);
+    }
+}
+
+/**
+ * Validated contents of `plugin.config.json`, with defaults for omitted keys.
+ * @typedef {object} PluginConfig
+ * @property {string[]} extraScripts Content-script paths relative to `src/`.
+ * @property {string[]} webviewScripts Webview-script paths relative to `src/`.
+ * @property {import('esbuild').BuildOptions} mainBuildOptions Overrides for the main bundle.
+ * @property {import('esbuild').BuildOptions} contentScriptBuildOptions Overrides for every content script.
+ * @property {import('esbuild').BuildOptions} webviewScriptBuildOptions Overrides for every webview script.
+ */
+
 /**
  * Reads and validates `<root>/plugin.config.json`. The file is optional; a plugin without one
- * has no extra or webview scripts and uses the default main build options.
- * @returns {Promise<{ extraScripts: string[], webviewScripts: string[], mainBuildOptions: import('esbuild').BuildOptions }>}
+ * has no extra or webview scripts and uses the default build options.
+ * @param {string} root Plugin project root.
+ * @returns {Promise<PluginConfig>}
  */
 export async function readPluginConfig(root) {
     const configPath = path.join(root, CONFIG_FILE);
@@ -174,34 +369,29 @@ export async function readPluginConfig(root) {
     try {
         config = JSON.parse(await readFile(configPath, 'utf8'));
     } catch (error) {
-        if (error.code === 'ENOENT') return { extraScripts: [], webviewScripts: [], mainBuildOptions: {} };
-        throw new Error(`Could not read ${configPath}: ${error.message}`, { cause: error });
+        if (!hasErrorCode(error, 'ENOENT')) {
+            throw new PluginScriptsError(`Could not read ${configPath}: ${errorMessage(error)}`, { cause: error });
+        }
+        config = {};
     }
-    if (!isPlainObject(config)) throw new Error(`${configPath} must contain a JSON object.`);
-    const { extraScripts = [], webviewScripts = [], mainBuildOptions = {}, ...unknown } = config;
+    if (!isPlainObject(config)) throw new PluginScriptsError(`${configPath} must contain a JSON object.`);
+    const {
+        extraScripts = [],
+        webviewScripts = [],
+        mainBuildOptions = {},
+        contentScriptBuildOptions = {},
+        webviewScriptBuildOptions = {},
+        ...unknown
+    } = config;
     const unknownKeys = Object.keys(unknown);
     if (unknownKeys.length > 0) {
-        throw new Error(`${configPath} has unknown keys: ${unknownKeys.join(', ')}.`);
-    }
-    for (const [key, value] of [
-        ['extraScripts', extraScripts],
-        ['webviewScripts', webviewScripts],
-    ]) {
-        if (!isStringArray(value)) {
-            throw new Error(`${configPath} "${key}" must be an array of paths relative to src/.`);
-        }
-    }
-    const outputs = scriptOutputPaths(extraScripts, webviewScripts);
-    const duplicate = outputs.find((output, index) => outputs.indexOf(output) !== index);
-    if (duplicate !== undefined) {
-        throw new Error(`${configPath} lists more than one script that builds to dist/${duplicate}.`);
-    }
-    if (!isPlainObject(mainBuildOptions)) {
-        throw new Error(`${configPath} "mainBuildOptions" must be an object of esbuild options.`);
-    }
-    const reserved = RESERVED_BUILD_OPTIONS.filter((key) => key in mainBuildOptions);
-    if (reserved.length > 0) {
-        throw new Error(`${configPath} "mainBuildOptions" cannot set ${reserved.join(', ')}.`);
+        throw new PluginScriptsError(`${configPath} has unknown keys: ${unknownKeys.join(', ')}.`);
     }
-    return { extraScripts, webviewScripts, mainBuildOptions };
+    assertScriptArray(extraScripts, 'extraScripts', configPath);
+    assertScriptArray(webviewScripts, 'webviewScripts', configPath);
+    assertValidScripts(configPath, extraScripts, webviewScripts);
+    assertBuildOptions(mainBuildOptions, 'mainBuildOptions', configPath);
+    assertBuildOptions(contentScriptBuildOptions, 'contentScriptBuildOptions', configPath);
+    assertBuildOptions(webviewScriptBuildOptions, 'webviewScriptBuildOptions', configPath);
+    return { extraScripts, webviewScripts, mainBuildOptions, contentScriptBuildOptions, webviewScriptBuildOptions };
 }

package/lib/errors.mjs

@@ -0,0 +1,27 @@
+/**
+ * Checks whether a caught value is an error with the given Node.js error code, e.g. `ENOENT`.
+ * @param {unknown} error
+ * @param {string} code
+ * @returns {boolean}
+ */
+export function hasErrorCode(error, code) {
+    return error instanceof Error && 'code' in error && error.code === code;
+}
+
+/**
+ * Returns a caught value's message for use in a wrapping error or warning.
+ * @param {unknown} error
+ * @returns {string}
+ */
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * An expected failure caused by the plugin project or its environment, such as invalid
+ * configuration or out-of-sync versions. The CLI prints only its message, without a stack trace;
+ * any other error is treated as a bug and shown in full.
+ */
+export class PluginScriptsError extends Error {
+    name = 'PluginScriptsError';
+}

package/lib/index.mjs

@@ -6,3 +6,4 @@ export {
     createWebviewScriptBuildOptions,
     readPluginConfig,
 } from './buildConfig.mjs';
+export { PluginScriptsError } from './errors.mjs';