@bwat47/joplin-plugin-scripts 1.1.0 → 1.2.0

package/lib/npm.mjs

@@ -0,0 +1,58 @@
+import { execFileSync } from 'node:child_process';
+import { statSync } from 'node:fs';
+import path from 'node:path';
+
+import { hasErrorCode, PluginScriptsError } from './errors.mjs';
+
+const NPM_NOT_FOUND = 'Could not find npm. Install npm and ensure its directory is on PATH, then retry update-api.';
+
+/**
+ * Finds npm without treating another package manager's npm_execpath as npm.
+ * Windows uses npm.exe or npm-cli.js directly to avoid a shell for npm.cmd.
+ * @param {{ platform?: string, npmExecPath?: string, nodePath?: string, searchPath?: string }} [options]
+ * @returns {{ file: string, args: string[] }}
+ */
+export function resolveNpmCommand({
+    platform = process.platform,
+    npmExecPath = process.env.npm_execpath,
+    nodePath = process.execPath,
+    searchPath = process.env.PATH ?? '',
+} = {}) {
+    if (npmExecPath && path.basename(npmExecPath) === 'npm-cli.js' && isFile(npmExecPath)) {
+        return { file: nodePath, args: [npmExecPath] };
+    }
+    if (platform !== 'win32') return { file: 'npm', args: [] };
+
+    const directories = [...searchPath.split(path.delimiter).filter(Boolean), path.dirname(nodePath)];
+    for (const directory of directories) {
+        const npmExe = path.join(directory, 'npm.exe');
+        if (isFile(npmExe)) return { file: npmExe, args: [] };
+        const npmCli = path.join(directory, 'node_modules', 'npm', 'bin', 'npm-cli.js');
+        if (isFile(npmCli)) return { file: nodePath, args: [npmCli] };
+    }
+    throw new PluginScriptsError(NPM_NOT_FOUND);
+}
+
+/** @param {string} file */
+function isFile(file) {
+    try {
+        return statSync(file).isFile();
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Runs npm with fixed arguments, without a shell.
+ * @param {string[]} args
+ * @param {string} cwd
+ */
+export function runNpm(args, cwd) {
+    const command = resolveNpmCommand();
+    try {
+        execFileSync(command.file, [...command.args, ...args], { cwd, stdio: 'pipe' });
+    } catch (error) {
+        if (hasErrorCode(error, 'ENOENT')) throw new PluginScriptsError(NPM_NOT_FOUND);
+        throw error;
+    }
+}

package/lib/packagePlugin.mjs

@@ -4,6 +4,25 @@ import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { create } from 'tar';
 
+import { errorMessage, hasErrorCode, PluginScriptsError } from './errors.mjs';
+
+/**
+ * Package metadata used by the build and version commands. Other fields are preserved.
+ * @typedef {object} PackageMetadata
+ * @property {string} name
+ * @property {string} version
+ * @property {string[]} [keywords]
+ */
+
+/**
+ * Plugin manifest fields used by validation and packaging. Other fields are preserved.
+ * @typedef {object} PluginManifest
+ * @property {string} id
+ * @property {string} version
+ * @property {string[]} [categories]
+ * @property {{ src: string }[]} [screenshots] Local or remote screenshots.
+ */
+
 /**
  * Plugin repository categories accepted in `manifest.categories`.
  * Mirrors generator-joplin's list; `update-api` warns when they differ.
@@ -34,46 +53,100 @@ const REMOTE_URL_PATTERN = /^https?:\/\//;
 /** Matches a valid plugin ID, e.g. `com.example.my-plugin` (letters, digits, `_`, `.`, `-`). */
 const PLUGIN_ID_PATTERN = /^[\w.-]+$/;
 
+/**
+ * Reads and parses a project JSON file, explaining a missing or malformed file without a stack trace.
+ * @param {string} root Plugin project root.
+ * @param {string} relativePath Path relative to `root`, e.g. `src/manifest.json`.
+ * @returns {Promise<any>}
+ */
+async function readProjectJson(root, relativePath) {
+    const filePath = path.join(root, relativePath);
+    let text;
+    try {
+        text = await readFile(filePath, 'utf8');
+    } catch (error) {
+        if (!hasErrorCode(error, 'ENOENT')) throw error;
+        throw new PluginScriptsError(`${filePath} not found; run this command from the plugin project root.`, {
+            cause: error,
+        });
+    }
+    try {
+        return JSON.parse(text);
+    } catch (error) {
+        throw new PluginScriptsError(`${filePath} is not valid JSON: ${errorMessage(error)}`, { cause: error });
+    }
+}
+
+/**
+ * Rejects a manifest screenshot without `src`, or a local one that is missing, of an unsupported
+ * type, or too large. Remote screenshots are not checked.
+ * @param {string} root Plugin project root.
+ * @param {{ src: string }} screenshot
+ */
+async function assertValidScreenshot(root, screenshot) {
+    if (!screenshot.src) throw new PluginScriptsError('Manifest screenshot must specify src.');
+    if (REMOTE_URL_PATTERN.test(screenshot.src)) return;
+    if (!SCREENSHOT_EXTENSIONS.has(path.extname(screenshot.src))) {
+        throw new PluginScriptsError(`Unsupported screenshot type: ${screenshot.src}`);
+    }
+    let size;
+    try {
+        ({ size } = await stat(path.join(root, screenshot.src)));
+    } catch (error) {
+        if (!hasErrorCode(error, 'ENOENT')) throw error;
+        throw new PluginScriptsError(`Screenshot not found: ${screenshot.src}`, { cause: error });
+    }
+    if (size > MAX_SCREENSHOT_BYTES) {
+        throw new PluginScriptsError(
+            `Screenshot exceeds ${MAX_SCREENSHOT_BYTES / (1024 * 1024)} MB: ${screenshot.src}`
+        );
+    }
+}
+
 /**
  * Reads `package.json` and `src/manifest.json` from `root` and validates the fields the plugin
  * repository depends on: plugin ID, matching versions, package name and keyword, categories, and
  * local screenshots.
+ * @param {string} root Plugin project root.
+ * @returns {Promise<{ packageJson: PackageMetadata, manifest: PluginManifest }>}
  */
 export async function readProject(root) {
-    const packageJson = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
-    const manifest = JSON.parse(await readFile(path.join(root, 'src/manifest.json'), 'utf8'));
+    /** @type {PackageMetadata} */
+    const packageJson = await readProjectJson(root, 'package.json');
+    /** @type {PluginManifest} */
+    const manifest = await readProjectJson(root, 'src/manifest.json');
     if (!manifest.id || !PLUGIN_ID_PATTERN.test(manifest.id)) {
-        throw new Error('Manifest plugin ID must contain only letters, digits, underscores, dots, or hyphens.');
+        throw new PluginScriptsError(
+            'Manifest plugin ID must contain only letters, digits, underscores, dots, or hyphens.'
+        );
     }
     if (manifest.version !== packageJson.version) {
-        throw new Error('package.json and src/manifest.json versions must match.');
+        throw new PluginScriptsError('package.json and src/manifest.json versions must match.');
     }
     if (!packageJson.name?.startsWith('joplin-plugin-') || !packageJson.keywords?.includes('joplin-plugin')) {
-        throw new Error('Package name must start with joplin-plugin- and keywords must include joplin-plugin.');
+        throw new PluginScriptsError(
+            'Package name must start with joplin-plugin- and keywords must include joplin-plugin.'
+        );
     }
     const selectedCategories = manifest.categories ?? [];
     if (
         new Set(selectedCategories).size !== selectedCategories.length ||
         selectedCategories.some((category) => !VALID_CATEGORIES.has(category))
     ) {
-        throw new Error('Manifest contains invalid or repeated categories.');
-    }
-    for (const screenshot of manifest.screenshots ?? []) {
-        if (!screenshot.src) throw new Error('Manifest screenshot must specify src.');
-        if (REMOTE_URL_PATTERN.test(screenshot.src)) continue;
-        if (!SCREENSHOT_EXTENSIONS.has(path.extname(screenshot.src))) {
-            throw new Error(`Unsupported screenshot type: ${screenshot.src}`);
-        }
-        if ((await stat(path.join(root, screenshot.src))).size > MAX_SCREENSHOT_BYTES) {
-            throw new Error(`Screenshot exceeds ${MAX_SCREENSHOT_BYTES / (1024 * 1024)} MB: ${screenshot.src}`);
-        }
+        throw new PluginScriptsError('Manifest contains invalid or repeated categories.');
     }
+    for (const screenshot of manifest.screenshots ?? []) await assertValidScreenshot(root, screenshot);
     return { packageJson, manifest };
 }
 
 /** Branch recorded in `_publish_commit` when the build runs from a detached HEAD. */
 const DEFAULT_BRANCH = 'main';
 
+/**
+ * Reads the branch and commit for publish metadata, or an empty string outside Git.
+ * @param {string} root Plugin project root.
+ * @returns {string}
+ */
 function currentGitInfo(root) {
     try {
         // Git is intentionally resolved from the developer's PATH, with fixed arguments and no shell.
@@ -90,7 +163,12 @@ function currentGitInfo(root) {
     }
 }
 
-/** Lists files under `directory`, skipping dotfiles and dot-directories (e.g. `.DS_Store`, `.gitkeep`). */
+/**
+ * Lists files under `directory`, skipping dotfiles and dot-directories (e.g. `.DS_Store`, `.gitkeep`).
+ * @param {string} directory
+ * @param {string} [prefix] Relative parent path, including its trailing slash.
+ * @returns {Promise<string[]>} Sorted file paths with forward slashes and the supplied prefix.
+ */
 async function listFiles(directory, prefix = '') {
     const files = [];
     for (const entry of await readdir(directory, { withFileTypes: true })) {
@@ -108,6 +186,9 @@ async function listFiles(directory, prefix = '') {
 /**
  * Archives `<root>/dist` into `<root>/publish/<id>.jpl` and writes `<id>.json` publish metadata.
  * `extraScripts` are bundle paths relative to `dist/` that must exist before packaging.
+ * @param {string} root Plugin project root.
+ * @param {PluginManifest} manifest Validated plugin manifest, including its plugin ID.
+ * @param {string[]} [extraScripts] Required bundle paths relative to `dist/`.
  */
 export async function packagePlugin(root, manifest, extraScripts = []) {
     const dist = path.join(root, 'dist');

package/lib/updateApi.mjs

@@ -1,10 +1,11 @@
-import { execFileSync } from 'node:child_process';
 import { cp, mkdtemp, readdir, readFile, rename, rm, stat } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { extract } from 'tar';
 
 import { contentScriptExternals } from './buildConfig.mjs';
+import { errorMessage, hasErrorCode } from './errors.mjs';
+import { runNpm } from './npm.mjs';
 import { VALID_CATEGORIES } from './packagePlugin.mjs';
 
 const templates = 'package/generators/app/templates';
@@ -31,26 +32,30 @@ const QUOTED_STRING_PATTERN = /["']([^"']+)["']/g;
 const LIST_SOURCE = '@bwat47/joplin-plugin-scripts';
 
 /**
- * Runs npm with fixed arguments. Under `npm run`, npm_execpath points at npm's CLI script,
- * which avoids spawning npm.cmd through a shell on Windows.
+ * Copies a source directory into a destination directory.
+ * @typedef {(from: string, to: string) => Promise<void>} CopyDirectory
  */
-function npm(args, cwd) {
-    const npmCli = process.env.npm_execpath;
-    if (npmCli?.endsWith('.js')) {
-        execFileSync(process.execPath, [npmCli, ...args], { cwd, stdio: 'pipe' });
-    } else if (process.platform === 'win32') {
-        throw new Error('Run update-api through an npm script, e.g. npm run updateApi');
-    } else {
-        // eslint-disable-next-line sonarjs/no-os-command-from-path -- Developer npm installation; arguments are passed without a shell.
-        execFileSync('npm', args, { cwd, stdio: 'pipe' });
-    }
-}
 
+/**
+ * Extracts string entries from a generator configuration list.
+ * @param {string} text
+ * @param {RegExp} listPattern Pattern capturing the list contents.
+ * @param {RegExp} itemPattern Global pattern capturing each entry.
+ * @returns {string[] | undefined}
+ */
 function extractList(text, listPattern, itemPattern) {
     const list = listPattern.exec(text)?.[1];
     return list === undefined ? undefined : [...list.matchAll(itemPattern)].map((match) => match[1]);
 }
 
+/**
+ * Describes missing or unexpected entries in a maintained list.
+ * @param {string} label List name for warning messages.
+ * @param {string[] | undefined} generatorItems Entries found in the generator, or `undefined` if the list was not found.
+ * @param {Iterable<string>} localItems Locally maintained entries.
+ * @param {string} location Source location to update.
+ * @returns {string | undefined}
+ */
 function describeListDifference(label, generatorItems, localItems, location) {
     if (generatorItems === undefined) {
         return `Could not find the ${label} in generator-joplin's webpack.config.js; compare ${location} manually.`;
@@ -71,6 +76,7 @@ function describeListDifference(label, generatorItems, localItems, location) {
  * Compares the hand-maintained category and content-script external lists with the ones in
  * generator-joplin's `webpack.config.js` text. Returns one warning per list that differs or
  * cannot be found; an empty array means both match.
+ * @param {string} webpackConfig
  * @returns {string[]}
  */
 export function compareGeneratorLists(webpackConfig) {
@@ -93,6 +99,9 @@ export function compareGeneratorLists(webpackConfig) {
 /**
  * Replaces `<root>/api` with a copy of `source`. The copy is staged next to `api/` and swapped in
  * by rename, so a failed copy leaves the existing `api/` untouched. `copy` defaults to a recursive copy.
+ * @param {string} root Plugin project root.
+ * @param {string} source
+ * @param {CopyDirectory} [copy] Copies the API into the staging directory.
  */
 export async function replaceApi(root, source, copy = (from, to) => cp(from, to, { recursive: true })) {
     // Fail before changing anything if the generator layout has changed.
@@ -106,7 +115,7 @@ export async function replaceApi(root, source, copy = (from, to) => cp(from, to,
         try {
             await rename(destination, backup);
         } catch (error) {
-            if (error.code !== 'ENOENT') throw error;
+            if (!hasErrorCode(error, 'ENOENT')) throw error;
             hadPrevious = false;
         }
         try {
@@ -121,12 +130,17 @@ export async function replaceApi(root, source, copy = (from, to) => cp(from, to,
     }
 }
 
+/**
+ * Reads the generator configuration and reports maintained-list differences.
+ * @param {string} webpackConfigPath
+ * @returns {Promise<string[]>}
+ */
 async function readGeneratorWarnings(webpackConfigPath) {
     let webpackConfig;
     try {
         webpackConfig = await readFile(webpackConfigPath, 'utf8');
     } catch (error) {
-        return [`Could not read ${webpackConfigPath} (${error.message}); compare the build lists manually.`];
+        return [`Could not read ${webpackConfigPath} (${errorMessage(error)}); compare the build lists manually.`];
     }
     return compareGeneratorLists(webpackConfig);
 }
@@ -135,12 +149,14 @@ async function readGeneratorWarnings(webpackConfigPath) {
  * Replaces `<root>/api` with the API declarations from the latest generator-joplin package.
  * Nothing else in the project is touched. Returns the generator version used and warnings for
  * hand-maintained build lists that no longer match the generator.
+ * @param {string} root Plugin project root.
+ * @param {string} [packageSpec] npm package specification for the generator to download.
  * @returns {Promise<{ version: string, warnings: string[] }>}
  */
 export async function updateApi(root, packageSpec = 'generator-joplin@latest') {
     const temp = await mkdtemp(path.join(tmpdir(), 'joplin-api-'));
     try {
-        npm(['pack', packageSpec, '--pack-destination', temp], temp);
+        runNpm(['pack', packageSpec, '--pack-destination', temp], temp);
         // The --json output shape differs between npm versions, so locate the tarball instead.
         const tarball = (await readdir(temp)).find((name) => name.endsWith('.tgz'));
         if (!tarball) throw new Error(`npm pack did not produce a tarball for ${packageSpec}`);

package/lib/updateVersion.mjs

@@ -1,14 +1,39 @@
 import { readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 
+import { PluginScriptsError } from './errors.mjs';
 import { readProject } from './packagePlugin.mjs';
 
 /** Matches a `major.minor.patch` version, e.g. `1.14.2`. */
 const SEMVER_PATTERN = /^\d+\.\d+\.\d+$/;
 
+/**
+ * Captures the newline and indent after a JSON file's opening brace, e.g. `{\r\n  "name"` captures
+ * `\r\n` and two spaces. This is how npm detects a lockfile's formatting.
+ */
+const JSON_FORMAT_PATTERN = /^\s*[{[]((?:\r?\n)+)([ \t]*)/;
+
+/**
+ * Serializes `value` in the formatting of `original`, as npm does when it rewrites a lockfile:
+ * the same indent and newline style, ending with one newline. Text without a newline after its
+ * opening brace (e.g. minified JSON) is written on one line, without a trailing newline.
+ * @param {unknown} value
+ * @param {string} original Text of the file being rewritten.
+ * @returns {string}
+ */
+function stringifyLike(value, original) {
+    const [, newlines = '', indent = ''] = JSON_FORMAT_PATTERN.exec(original) ?? [];
+    const newline = newlines.startsWith('\r\n') ? '\r\n' : newlines.slice(0, 1);
+    return `${JSON.stringify(value, null, indent)}\n`.replaceAll('\n', newline);
+}
+
 /**
  * Returns the text of a hand-formatted JSON file with its single `"version": "<from>"` entry
  * replaced, leaving every other byte untouched so a version bump produces a one-line diff.
+ * @param {string} filePath
+ * @param {string} from Current version in major.minor.patch format.
+ * @param {string} to Replacement version in major.minor.patch format.
+ * @returns {Promise<string>}
  */
 async function replaceVersion(filePath, from, to) {
     const text = await readFile(filePath, 'utf8');
@@ -16,7 +41,7 @@ async function replaceVersion(filePath, from, to) {
     const pattern = new RegExp(`("version"\\s*:\\s*")${from.replaceAll('.', '\\.')}(")`, 'g');
     const matches = text.match(pattern)?.length ?? 0;
     if (matches !== 1) {
-        throw new Error(`Expected one "version": "${from}" entry in ${filePath}, found ${matches}.`);
+        throw new PluginScriptsError(`Expected one "version": "${from}" entry in ${filePath}, found ${matches}.`);
     }
     return text.replace(pattern, `$1${to}$2`);
 }
@@ -24,25 +49,29 @@ async function replaceVersion(filePath, from, to) {
 /**
  * Increments the patch version in `package.json`, `src/manifest.json`, and `package-lock.json`
  * together. Writes nothing unless all three files can be updated.
+ * @param {string} root Plugin project root.
  * @returns {Promise<string>} The new version.
  */
 export async function updateVersion(root) {
     const { packageJson } = await readProject(root);
     const current = packageJson.version;
     if (!SEMVER_PATTERN.test(current)) {
-        throw new Error('update-version requires a version in major.minor.patch format.');
+        throw new PluginScriptsError('update-version requires a version in major.minor.patch format.');
     }
     const [major, minor, patch] = current.split('.').map(Number);
     const version = `${major}.${minor}.${patch + 1}`;
 
     const lockPath = path.join(root, 'package-lock.json');
-    const lock = JSON.parse(await readFile(lockPath, 'utf8'));
+    const lockText = await readFile(lockPath, 'utf8');
+    const lock = JSON.parse(lockText);
     const lockRoot = lock.packages?.[''];
     if (!lockRoot) {
-        throw new Error(`${lockPath} has no root package entry (packages[""]); regenerate it with npm install.`);
+        throw new PluginScriptsError(
+            `${lockPath} has no root package entry (packages[""]); regenerate it with npm install.`
+        );
     }
     if (lock.version !== current || lockRoot.version !== current) {
-        throw new Error(
+        throw new PluginScriptsError(
             `${lockPath} versions (${lock.version}, ${lockRoot.version}) do not match package.json (${current}); ` +
                 'run npm install to resync the lockfile.'
         );
@@ -56,8 +85,9 @@ export async function updateVersion(root) {
     const updates = [
         [packagePath, await replaceVersion(packagePath, current, version)],
         [manifestPath, await replaceVersion(manifestPath, current, version)],
-        // npm owns the lockfile format, which is JSON.stringify output; dependencies may share the version string.
-        [lockPath, `${JSON.stringify(lock, null, 4)}\n`],
+        // npm owns the lockfile format, which is JSON.stringify output in the file's detected indent and
+        // newline style; it is reserialized rather than patched because dependencies may share the version string.
+        [lockPath, stringifyLike(lock, lockText)],
     ];
     for (const [filePath, text] of updates) await writeFile(filePath, text);
     return version;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@bwat47/joplin-plugin-scripts",
-    "version": "1.1.0",
+    "version": "1.2.0",
     "description": "Shared esbuild build, packaging, version, and API-update scripts for Joplin plugins",
     "license": "MIT",
     "author": "bwat47",
@@ -16,19 +16,26 @@
         "joplin-plugin-scripts": "bin/joplin-plugin-scripts.mjs"
     },
     "exports": {
-        ".": "./lib/index.mjs"
+        ".": {
+            "types": "./types/index.d.mts",
+            "default": "./lib/index.mjs"
+        }
     },
     "files": [
         "bin",
-        "lib"
+        "lib",
+        "types"
     ],
     "scripts": {
         "test": "node --test test/*.test.mjs",
+        "typecheck": "tsc --project tsconfig.json",
+        "build:types": "node -e \"require('node:fs').rmSync('types', { recursive: true, force: true })\" && tsc --project tsconfig.build.json",
+        "prepack": "npm run build:types",
         "lint": "eslint .",
         "lint:fix": "eslint . --fix",
         "format": "prettier --write .",
         "format:check": "prettier --check .",
-        "prepublishOnly": "npm run lint && npm run format:check && npm test"
+        "prepublishOnly": "npm run typecheck && npm run lint && npm run format:check && npm test"
     },
     "dependencies": {
         "esbuild": "^0.28.2",
@@ -37,10 +44,12 @@
     "devDependencies": {
         "@eslint/js": "^10.0.1",
         "@ianvs/prettier-plugin-sort-imports": "^4.7.1",
+        "@types/node": "^22.20.5",
         "eslint": "^10.14.0",
         "eslint-config-prettier": "^10.1.8",
         "eslint-plugin-sonarjs": "^4.2.2",
         "globals": "^17.14.0",
-        "prettier": "^3.9.10"
+        "prettier": "^3.9.10",
+        "typescript": "^6.0.3"
     }
 }

package/types/build.d.mts

@@ -0,0 +1,7 @@
+/**
+ * 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 function buildPlugin(root: string): Promise<void>;

package/types/buildConfig.d.mts

@@ -0,0 +1,88 @@
+/**
+ * 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: string, source: string): boolean;
+/**
+ * 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: string, overrides?: import("esbuild").BuildOptions): import("esbuild").BuildOptions;
+/**
+ * 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: string, script: string, overrides?: import("esbuild").BuildOptions): import("esbuild").BuildOptions;
+/**
+ * Returns the esbuild options for one webview script, e.g. `dialog/resizeDialog.ts` (relative to
+ * `src/`) to `dist/dialog/resizeDialog.js`. Webview scripts are loaded by a `<script>` tag in a
+ * dialog or panel, which has no `module`, `exports`, or `require`, so they are bundled as a
+ * 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: string, script: string, overrides?: import("esbuild").BuildOptions): import("esbuild").BuildOptions;
+/**
+ * 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: string[], webviewScripts: string[]): string[];
+/**
+ * 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 build options.
+ * @param {string} root Plugin project root.
+ * @returns {Promise<PluginConfig>}
+ */
+export function readPluginConfig(root: string): Promise<PluginConfig>;
+/** Name of the optional per-plugin build configuration file at the project root. */
+export const CONFIG_FILE: "plugin.config.json";
+export const contentScriptExternals: string[];
+/**
+ * Validated contents of `plugin.config.json`, with defaults for omitted keys.
+ */
+export type PluginConfig = {
+    /**
+     * Content-script paths relative to `src/`.
+     */
+    extraScripts: string[];
+    /**
+     * Webview-script paths relative to `src/`.
+     */
+    webviewScripts: string[];
+    /**
+     * Overrides for the main bundle.
+     */
+    mainBuildOptions: import("esbuild").BuildOptions;
+    /**
+     * Overrides for every content script.
+     */
+    contentScriptBuildOptions: import("esbuild").BuildOptions;
+    /**
+     * Overrides for every webview script.
+     */
+    webviewScriptBuildOptions: import("esbuild").BuildOptions;
+};

package/types/errors.d.mts

@@ -0,0 +1,20 @@
+/**
+ * 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: unknown, code: string): boolean;
+/**
+ * Returns a caught value's message for use in a wrapping error or warning.
+ * @param {unknown} error
+ * @returns {string}
+ */
+export function errorMessage(error: unknown): string;
+/**
+ * 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 {
+}

package/types/index.d.mts

@@ -0,0 +1,2 @@
+export { PluginScriptsError } from "./errors.mjs";
+export { contentScriptExternals, createBuildOptions, createContentScriptBuildOptions, createWebviewScriptBuildOptions, readPluginConfig } from "./buildConfig.mjs";

package/types/npm.d.mts

@@ -0,0 +1,21 @@
+/**
+ * Finds npm without treating another package manager's npm_execpath as npm.
+ * Windows uses npm.exe or npm-cli.js directly to avoid a shell for npm.cmd.
+ * @param {{ platform?: string, npmExecPath?: string, nodePath?: string, searchPath?: string }} [options]
+ * @returns {{ file: string, args: string[] }}
+ */
+export function resolveNpmCommand({ platform, npmExecPath, nodePath, searchPath, }?: {
+    platform?: string;
+    npmExecPath?: string;
+    nodePath?: string;
+    searchPath?: string;
+}): {
+    file: string;
+    args: string[];
+};
+/**
+ * Runs npm with fixed arguments, without a shell.
+ * @param {string[]} args
+ * @param {string} cwd
+ */
+export function runNpm(args: string[], cwd: string): void;