@bwat47/joplin-plugin-scripts 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bwat47
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# @bwat47/joplin-plugin-scripts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared build tooling for Joplin plugins: an esbuild-based replacement for the
+generator-joplin Webpack config and its scripts.
+
+## Usage
+
+```sh
+npm install -D @bwat47/joplin-plugin-scripts
+```
+
+```json
+"scripts": {
+    "dist": "npm run typecheck && joplin-plugin-scripts build",
+    "updateVersion": "joplin-plugin-scripts update-version",
+    "updateApi": "joplin-plugin-scripts update-api"
+}
+```
+
+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.                     |
+
+### Project layout expected
+
+- `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.
+- `src/manifest.json` and `package.json`: versions must match; the package name starts
+  with `joplin-plugin-` and `keywords` includes `joplin-plugin`.
+- `api/`: resolved through `tsconfig.json` `paths` (`api` and `api/*`).
+- Other files in `src/` are copied to `dist/`, except TypeScript sources, `*.test.*` /
+  `*.spec.*` files, and anything under `fixtures/` or `__tests__/` directories.
+
+### `plugin.config.json` (optional)
+
+```json
+{
+    "extraScripts": ["contentScripts/codeMirror.ts"],
+    "mainBuildOptions": { "external": ["jsdom"] }
+}
+```
+
+- `extraScripts`: content scripts relative to `src/`, bundled for the browser 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.
+- `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.
+
+### Testing a plugin's bundles
+
+The package exports the same esbuild options the build uses, so plugin tests can build
+in memory and run the result:
+
+```js
+import { createBuildOptions, createContentScriptBuildOptions, readPluginConfig } from '@bwat47/joplin-plugin-scripts';
+
+const { mainBuildOptions } = await readPluginConfig(root);
+const result = await build({ ...createBuildOptions(root, mainBuildOptions), write: false });
+```
+
+`contentScriptExternals` is also exported.
+
+## Development
+
+```sh
+npm test
+npm run lint
+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).

package/bin/joplin-plugin-scripts.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { buildPlugin } from '../lib/build.mjs';
+import { updateApi } from '../lib/updateApi.mjs';
+import { updateVersion } from '../lib/updateVersion.mjs';
+
+const USAGE = `Usage: joplin-plugin-scripts <command>
+
+Run from a Joplin plugin project root (npm scripts do this automatically).
+
+Commands:
+  build           Bundle the plugin with esbuild and create publish/<id>.jpl
+  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`;
+
+const commands = {
+    build: async (root) => {
+        await buildPlugin(root);
+    },
+    'update-version': async (root) => {
+        console.info(`Updated version to ${await updateVersion(root)}.`);
+    },
+    'update-api': async (root) => {
+        const { version, warnings } = await updateApi(root);
+        console.info(`Updated api/ from generator-joplin ${version}. Review with: git diff api/`);
+        for (const warning of warnings) console.warn(`WARNING: ${warning}`);
+    },
+};
+
+const [command, ...rest] = process.argv.slice(2);
+if (command === '--help' || command === '-h') {
+    console.info(USAGE);
+    process.exit(0);
+}
+const run = Object.hasOwn(commands, command) ? commands[command] : undefined;
+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());

package/lib/build.mjs

@@ -0,0 +1,44 @@
+import { cp, mkdir, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { build } from 'esbuild';
+
+import {
+    createBuildOptions,
+    createContentScriptBuildOptions,
+    isRuntimeAsset,
+    readPluginConfig,
+} from './buildConfig.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 and extra scripts, and creates the `.jpl` archive.
+ */
+export async function buildPlugin(root) {
+    const dist = path.join(root, 'dist');
+    const publish = path.join(root, 'publish');
+    const { manifest } = await readProject(root);
+    const { extraScripts, mainBuildOptions } = await readPluginConfig(root);
+    const extraBuilds = extraScripts.map((script) => createContentScriptBuildOptions(root, script));
+
+    // Only these fixed, project-local output directories are removed.
+    await rm(dist, { recursive: true, force: true });
+    await rm(publish, { recursive: true, force: true });
+    await mkdir(dist, { recursive: true });
+
+    // Copy first so a JavaScript source asset cannot overwrite a compiled bundle.
+    await cp(path.join(root, 'src'), dist, {
+        recursive: true,
+        filter: (source) => isRuntimeAsset(root, source),
+    });
+    await Promise.all([
+        build(createBuildOptions(root, mainBuildOptions)),
+        ...extraBuilds.map((options) => build(options)),
+    ]);
+
+    await packagePlugin(
+        root,
+        manifest,
+        extraBuilds.map((options) => path.relative(dist, path.resolve(root, options.outfile)))
+    );
+}

package/lib/buildConfig.mjs

@@ -0,0 +1,170 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+/** Name of the optional per-plugin build configuration file at the project root. */
+export const CONFIG_FILE = 'plugin.config.json';
+
+/**
+ * Matches TypeScript sources, which are bundled rather than copied,
+ * e.g. `index.ts`, `view.tsx`, `worker.mts`, `config.cts`, `types.d.ts` (not `notes.txt`).
+ */
+const TYPESCRIPT_SOURCE_PATTERN = /\.(?:[cm]?ts|tsx)$/;
+
+/** Matches a bundleable script extension, e.g. `a.ts`, `a.tsx`, `a.js`, `a.jsx` (not `a.json`, `a.css`). */
+const SCRIPT_EXTENSION_PATTERN = /\.[jt]sx?$/;
+
+/** Splits a path on either separator, e.g. `a/b\c` becomes `['a', 'b', 'c']`. */
+const PATH_SEPARATOR_PATTERN = /[\\/]/;
+
+/** Matches test files, e.g. `pipeline.test.ts` or `render.spec.js`. */
+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'];
+
+/** Excludes bundled sources, tests, and development fixtures in `<root>/src` from copied runtime assets. */
+export function isRuntimeAsset(root, source) {
+    const parts = path.relative(path.join(root, 'src'), source).split(PATH_SEPARATOR_PATTERN);
+    return (
+        !TYPESCRIPT_SOURCE_PATTERN.test(source) &&
+        !TEST_FILE_PATTERN.test(source) &&
+        !parts.some((part) => part === 'fixtures' || part === '__tests__')
+    );
+}
+
+// Keep the generator's explicit host-library list: these must share Joplin's instances.
+// `update-api` warns when this list differs from the generator's.
+export const contentScriptExternals = [
+    '@codemirror/view',
+    '@codemirror/state',
+    '@codemirror/search',
+    '@codemirror/language',
+    '@codemirror/autocomplete',
+    '@codemirror/commands',
+    '@codemirror/highlight',
+    '@codemirror/lint',
+    '@codemirror/lang-html',
+    '@codemirror/lang-markdown',
+    '@codemirror/language-data',
+    '@lezer/common',
+    '@lezer/markdown',
+    '@lezer/highlight',
+];
+
+/**
+ * Rewrites Node built-in imports to their bare names, e.g. `node:path` to `path`,
+ * matching the generator's Webpack build for Joplin's plugin runtime.
+ * @type {import('esbuild').Plugin}
+ */
+const stripNodePrefix = {
+    name: 'strip-node-prefix',
+    setup(pluginBuild) {
+        pluginBuild.onResolve({ filter: NODE_PREFIX_PATTERN }, (args) => ({
+            path: args.path.slice('node:'.length),
+            external: true,
+        }));
+    },
+};
+
+/**
+ * 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.
+ * @returns {import('esbuild').BuildOptions}
+ */
+function sharedOptions(root) {
+    return {
+        absWorkingDir: root,
+        bundle: true,
+        format: 'cjs',
+        target: 'es2020',
+        minify: true,
+        // Matches Webpack's production mode. esbuild only sets this automatically for minified browser builds,
+        // and the main bundle may run in a webview without `process` (mobile).
+        define: { 'process.env.NODE_ENV': '"production"' },
+        logLevel: 'info',
+    };
+}
+
+/**
+ * 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.
+ * @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 = {}) {
+    return {
+        ...sharedOptions(root),
+        entryPoints: ['src/index.ts'],
+        outfile: 'dist/index.js',
+        platform: 'node',
+        plugins: [stripNodePrefix],
+        ...overrides,
+    };
+}
+
+/**
+ * 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.
+ * @param {string} script Script path relative to `src/`.
+ * @returns {import('esbuild').BuildOptions}
+ */
+export function createContentScriptBuildOptions(root, script) {
+    if (
+        !SCRIPT_EXTENSION_PATTERN.test(script) ||
+        path.isAbsolute(script) ||
+        script.split(PATH_SEPARATOR_PATTERN).includes('..')
+    ) {
+        throw new Error(`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.
+    return {
+        ...sharedOptions(root),
+        entryPoints: [`src/${script}`],
+        outfile: `dist/${script.replace(SCRIPT_EXTENSION_PATTERN, '.js')}`,
+        external: contentScriptExternals,
+    };
+}
+
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Reads and validates `<root>/plugin.config.json`. The file is optional; a plugin without one
+ * has no extra scripts and uses the default main build options.
+ * @returns {Promise<{ extraScripts: string[], mainBuildOptions: import('esbuild').BuildOptions }>}
+ */
+export async function readPluginConfig(root) {
+    const configPath = path.join(root, CONFIG_FILE);
+    let config;
+    try {
+        config = JSON.parse(await readFile(configPath, 'utf8'));
+    } catch (error) {
+        if (error.code === 'ENOENT') return { extraScripts: [], mainBuildOptions: {} };
+        throw new Error(`Could not read ${configPath}: ${error.message}`, { cause: error });
+    }
+    if (!isPlainObject(config)) throw new Error(`${configPath} must contain a JSON object.`);
+    const { extraScripts = [], mainBuildOptions = {}, ...unknown } = config;
+    const unknownKeys = Object.keys(unknown);
+    if (unknownKeys.length > 0) {
+        throw new Error(`${configPath} has unknown keys: ${unknownKeys.join(', ')}.`);
+    }
+    if (!Array.isArray(extraScripts) || extraScripts.some((script) => typeof script !== 'string')) {
+        throw new Error(`${configPath} "extraScripts" must be an array of paths relative to src/.`);
+    }
+    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(', ')}.`);
+    }
+    return { extraScripts, mainBuildOptions };
+}

package/lib/index.mjs

@@ -0,0 +1,7 @@
+// Public API for plugin projects' own build tests. The CLI in bin/ is the main entry point.
+export {
+    contentScriptExternals,
+    createBuildOptions,
+    createContentScriptBuildOptions,
+    readPluginConfig,
+} from './buildConfig.mjs';

package/lib/packagePlugin.mjs

@@ -0,0 +1,128 @@
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { create } from 'tar';
+
+/**
+ * Plugin repository categories accepted in `manifest.categories`.
+ * Mirrors generator-joplin's list; `update-api` warns when they differ.
+ */
+export const VALID_CATEGORIES = new Set([
+    'appearance',
+    'developer tools',
+    'productivity',
+    'themes',
+    'integrations',
+    'viewer',
+    'search',
+    'tags',
+    'editor',
+    'files',
+    'personal knowledge management',
+]);
+
+/** File extensions accepted for local manifest screenshots. */
+const SCREENSHOT_EXTENSIONS = new Set(['.jpg', '.jpeg', '.png', '.gif', '.webp']);
+
+/** Maximum size of a local manifest screenshot. */
+const MAX_SCREENSHOT_BYTES = 1024 * 1024;
+
+/** Matches a remote screenshot URL, which is not validated locally, e.g. `https://example.com/a.png`. */
+const REMOTE_URL_PATTERN = /^https?:\/\//;
+
+/** Matches a valid plugin ID, e.g. `com.example.my-plugin` (letters, digits, `_`, `.`, `-`). */
+const PLUGIN_ID_PATTERN = /^[\w.-]+$/;
+
+/**
+ * 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.
+ */
+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'));
+    if (!manifest.id || !PLUGIN_ID_PATTERN.test(manifest.id)) {
+        throw new Error('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.');
+    }
+    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.');
+    }
+    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}`);
+        }
+    }
+    return { packageJson, manifest };
+}
+
+/** Branch recorded in `_publish_commit` when the build runs from a detached HEAD. */
+const DEFAULT_BRANCH = 'main';
+
+function currentGitInfo(root) {
+    try {
+        // Git is intentionally resolved from the developer's PATH, with fixed arguments and no shell.
+        // eslint-disable-next-line sonarjs/no-os-command-from-path -- Local build tool using the developer's Git installation.
+        const branch = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: root, stdio: 'pipe' })
+            .toString()
+            .trim();
+        // eslint-disable-next-line sonarjs/no-os-command-from-path -- Fixed Git arguments, without a shell.
+        const commit = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: root, stdio: 'pipe' }).toString().trim();
+        // A detached HEAD (e.g. a CI tag checkout) reports `HEAD`; record the default branch instead.
+        return `${branch === 'HEAD' ? DEFAULT_BRANCH : branch}:${commit}`;
+    } catch {
+        return '';
+    }
+}
+
+/** Lists files under `directory`, skipping dotfiles and dot-directories (e.g. `.DS_Store`, `.gitkeep`). */
+async function listFiles(directory, prefix = '') {
+    const files = [];
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+        if (entry.name.startsWith('.')) continue;
+        const relativePath = `${prefix}${entry.name}`;
+        if (entry.isDirectory()) {
+            files.push(...(await listFiles(path.join(directory, entry.name), `${relativePath}/`)));
+        } else {
+            files.push(relativePath);
+        }
+    }
+    return files.sort();
+}
+
+/**
+ * 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.
+ */
+export async function packagePlugin(root, manifest, extraScripts = []) {
+    const dist = path.join(root, 'dist');
+    const publish = path.join(root, 'publish');
+    // Require the entry point and manifest, rather than publishing an incomplete build.
+    await stat(path.join(dist, 'index.js'));
+    await stat(path.join(dist, 'manifest.json'));
+    for (const script of extraScripts) await stat(path.join(dist, script));
+    await mkdir(publish, { recursive: true });
+    const archivePath = path.join(publish, `${manifest.id}.jpl`);
+    // Package files only, matching the generator and excluding empty source directories.
+    await create({ cwd: dist, file: archivePath, portable: true, strict: true }, await listFiles(dist));
+    const hash = createHash('sha256')
+        .update(await readFile(archivePath))
+        .digest('hex');
+    const info = { ...manifest, _publish_hash: `sha256:${hash}`, _publish_commit: currentGitInfo(root) };
+    await writeFile(path.join(publish, `${manifest.id}.json`), `${JSON.stringify(info, null, 4)}\n`);
+}

package/lib/updateApi.mjs

@@ -0,0 +1,155 @@
+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 { VALID_CATEGORIES } from './packagePlugin.mjs';
+
+const templates = 'package/generators/app/templates';
+
+/**
+ * Matches the generator's category list, e.g.
+ * `const allPossibleCategories = [{'name':'appearance'},{'name':'editor'}];`
+ */
+const GENERATOR_CATEGORIES_PATTERN = /const allPossibleCategories = \[(.*?)\];/s;
+
+/** Matches one category entry within that list, e.g. `{'name':'developer tools'}` captures `developer tools`. */
+const GENERATOR_CATEGORY_NAME_PATTERN = /["']name["']\s*:\s*["']([^"']+)["']/g;
+
+/**
+ * Matches the generator's content-script externals, e.g.
+ * `const externalContentScriptLibraries = [\n\t'@codemirror/view',\n\t'@lezer/common',\n];`
+ */
+const GENERATOR_EXTERNALS_PATTERN = /const externalContentScriptLibraries = \[([^\]]*)\]/;
+
+/** Matches one quoted string, e.g. `'@codemirror/view'` captures `@codemirror/view`. */
+const QUOTED_STRING_PATTERN = /["']([^"']+)["']/g;
+
+/** Where the hand-maintained lists live, for warnings shown in plugin projects. */
+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.
+ */
+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' });
+    }
+}
+
+function extractList(text, listPattern, itemPattern) {
+    const list = listPattern.exec(text)?.[1];
+    return list === undefined ? undefined : [...list.matchAll(itemPattern)].map((match) => match[1]);
+}
+
+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.`;
+    }
+    const local = new Set(localItems);
+    const generator = new Set(generatorItems);
+    const missing = [...generator].filter((item) => !local.has(item));
+    const extra = [...local].filter((item) => !generator.has(item));
+    if (missing.length === 0 && extra.length === 0) return undefined;
+    const details = [
+        missing.length > 0 ? `missing ${missing.join(', ')}` : '',
+        extra.length > 0 ? `not in generator ${extra.join(', ')}` : '',
+    ].filter(Boolean);
+    return `The ${label} differ from generator-joplin (${details.join('; ')}); update ${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.
+ * @returns {string[]}
+ */
+export function compareGeneratorLists(webpackConfig) {
+    return [
+        describeListDifference(
+            'plugin categories',
+            extractList(webpackConfig, GENERATOR_CATEGORIES_PATTERN, GENERATOR_CATEGORY_NAME_PATTERN),
+            VALID_CATEGORIES,
+            `VALID_CATEGORIES in ${LIST_SOURCE} (lib/packagePlugin.mjs)`
+        ),
+        describeListDifference(
+            'content-script externals',
+            extractList(webpackConfig, GENERATOR_EXTERNALS_PATTERN, QUOTED_STRING_PATTERN),
+            contentScriptExternals,
+            `contentScriptExternals in ${LIST_SOURCE} (lib/buildConfig.mjs)`
+        ),
+    ].filter((warning) => warning !== undefined);
+}
+
+/**
+ * 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.
+ */
+export async function replaceApi(root, source, copy = (from, to) => cp(from, to, { recursive: true })) {
+    // Fail before changing anything if the generator layout has changed.
+    await stat(path.join(source, 'index.ts'));
+    const destination = path.join(root, 'api');
+    const staging = await mkdtemp(path.join(root, '.api-staging-'));
+    const backup = `${staging}-previous`;
+    try {
+        await copy(source, staging);
+        let hadPrevious = true;
+        try {
+            await rename(destination, backup);
+        } catch (error) {
+            if (error.code !== 'ENOENT') throw error;
+            hadPrevious = false;
+        }
+        try {
+            await rename(staging, destination);
+        } catch (error) {
+            if (hadPrevious) await rename(backup, destination);
+            throw error;
+        }
+        if (hadPrevious) await rm(backup, { recursive: true, force: true });
+    } finally {
+        await rm(staging, { recursive: true, force: true });
+    }
+}
+
+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 compareGeneratorLists(webpackConfig);
+}
+
+/**
+ * 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.
+ * @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);
+        // 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}`);
+        await extract({ file: path.join(temp, tarball), cwd: temp, strict: true });
+        const { version } = JSON.parse(await readFile(path.join(temp, 'package/package.json'), 'utf8'));
+        await replaceApi(root, path.join(temp, templates, 'api'));
+        const warnings = await readGeneratorWarnings(path.join(temp, templates, 'webpack.config.js'));
+        return { version, warnings };
+    } finally {
+        await rm(temp, { recursive: true, force: true });
+    }
+}

package/lib/updateVersion.mjs

@@ -0,0 +1,64 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { readProject } from './packagePlugin.mjs';
+
+/** Matches a `major.minor.patch` version, e.g. `1.14.2`. */
+const SEMVER_PATTERN = /^\d+\.\d+\.\d+$/;
+
+/**
+ * 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.
+ */
+async function replaceVersion(filePath, from, to) {
+    const text = await readFile(filePath, 'utf8');
+    // e.g. `"version": "1.14.2"`; `from` is validated semver, so only its dots need escaping.
+    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}.`);
+    }
+    return text.replace(pattern, `$1${to}$2`);
+}
+
+/**
+ * Increments the patch version in `package.json`, `src/manifest.json`, and `package-lock.json`
+ * together. Writes nothing unless all three files can be updated.
+ * @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.');
+    }
+    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 lockRoot = lock.packages?.[''];
+    if (!lockRoot) {
+        throw new Error(`${lockPath} has no root package entry (packages[""]); regenerate it with npm install.`);
+    }
+    if (lock.version !== current || lockRoot.version !== current) {
+        throw new Error(
+            `${lockPath} versions (${lock.version}, ${lockRoot.version}) do not match package.json (${current}); ` +
+                'run npm install to resync the lockfile.'
+        );
+    }
+    lock.version = version;
+    lockRoot.version = version;
+
+    const packagePath = path.join(root, 'package.json');
+    const manifestPath = path.join(root, 'src/manifest.json');
+    // Prepare every file before writing any, so a failed check leaves all versions in sync.
+    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`],
+    ];
+    for (const [filePath, text] of updates) await writeFile(filePath, text);
+    return version;
+}

package/package.json

@@ -1,6 +1,42 @@
 {
-  "name": "@bwat47/joplin-plugin-scripts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@bwat47/joplin-plugin-scripts",
+    "version": "1.0.0",
+    "description": "Shared esbuild build, packaging, version, and API-update scripts for Joplin plugins",
+    "license": "MIT",
+    "author": "bwat47",
+    "type": "module",
+    "engines": {
+        "node": ">=22"
+    },
+    "bin": {
+        "joplin-plugin-scripts": "bin/joplin-plugin-scripts.mjs"
+    },
+    "exports": {
+        ".": "./lib/index.mjs"
+    },
+    "files": [
+        "bin",
+        "lib"
+    ],
+    "scripts": {
+        "test": "node --test test/*.test.mjs",
+        "lint": "eslint .",
+        "lint:fix": "eslint . --fix",
+        "format": "prettier --write .",
+        "format:check": "prettier --check .",
+        "prepublishOnly": "npm run lint && npm run format:check && npm test"
+    },
+    "dependencies": {
+        "esbuild": "^0.28.2",
+        "tar": "^7.5.22"
+    },
+    "devDependencies": {
+        "@eslint/js": "^10.0.1",
+        "@ianvs/prettier-plugin-sort-imports": "^4.7.1",
+        "eslint": "^10.14.0",
+        "eslint-config-prettier": "^10.1.8",
+        "eslint-plugin-sonarjs": "^4.2.2",
+        "globals": "^17.14.0",
+        "prettier": "^3.9.10"
+    }
+}