iifeify 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Florian Noever
+
+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,203 @@
-# Temporary Holding Version
+# iifeify
 
-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.
+Turn an npm package into one classic browser script.
+
+```bash
+npx iifeify vanilla-jsoneditor@3.13.0 --entry standalone.js --global-name VanillaJsonEditor
+```
+
+This writes `vanilla-jsoneditor.iife.js`. Loaded with a plain `<script>` tag, the file defines the global `VanillaJsonEditor`, which holds everything the package exports. The file starts with a license banner generated from the package's own metadata:
+
+```js
+/*! vanilla-jsoneditor 3.13.0 - Copyright (c) 2020-2026 by Jos de Jong - ISC License - https://github.com/josdejong/svelte-jsoneditor */
+var VanillaJsonEditor=(()=>{ ... })();
+```
+
+iifeify is for hosts that accept only classic scripts and cannot `import` anything, such as control add-ins in Microsoft Dynamics 365 Business Central.
+
+---
+
+## ✨ Features
+
+- **Any npm package** — installed with npm itself, so versions, ranges, tags, scoped packages, private registries and proxies work as they do for `npm install`
+- **One file, one global** — the package and every dependency it imports, bundled with [esbuild](https://esbuild.github.io/) into an IIFE
+- **License banner** — one line per bundled package with its version, copyright notice, license and web address, read from its `package.json` and license file
+- **Full license texts** — `--notices` writes the license and notice files of all bundled packages next to the script
+- **Browser check** — a package that imports `fs`, `path` or another Node.js built-in is refused, with the modules and the files that import them
+
+---
+
+## 🚀 Installation
+
+Run it directly with `npx`, no installation required:
+
+```bash
+npx iifeify <package>
+```
+
+Or install it globally:
+
+```bash
+npm install -g iifeify
+```
+
+---
+
+## 🧰 Usage
+
+```bash
+npx iifeify <package>[@version] [options]
+```
+
+`<package>` is a package name as you would give it to `npm install`: `ms`, `ms@2.1.3`, `ms@^2`, `@codemirror/state`.
+
+| Option | Meaning | Default |
+| --- | --- | --- |
+| `-e`, `--entry <path>` | File or subpath inside the package to bundle | The package's own browser entry |
+| `-g`, `--global-name <name>` | Global variable the script defines | The package name in PascalCase |
+| `-o`, `--outfile <file>` | Where to write the script | `./<package>.iife.js` |
+| `--no-minify` | Keep the output readable | Minified |
+| `--target <list>` | Language level of the output, for example `es2020` | `esnext` |
+| `--notices` | Also write the full license texts next to the script, for example `ms.iife.LICENSES.txt` | Off |
+| `-h`, `--help` | Show the help | |
+| `-v`, `--version` | Show the version | |
+
+The exit code is 0 on success, 1 if the package cannot be converted and 2 for a wrong command line.
+
+### How it works
+
+1. iifeify runs `npm install` for the package in a temporary folder. It uses your npm configuration, so private registries and proxies work. Install scripts are not run.
+2. It bundles the package and the dependencies it imports into one file with esbuild, in the `iife` format with your global name.
+3. It reads `package.json` and the license file of every package that ended up in the bundle and writes the banner.
+4. It removes the temporary folder.
+
+### Which file is bundled
+
+Without `--entry`, iifeify bundles what a bundler picks for an `import` of the package in browser code: the package's `exports` (conditions `browser`, `import`, `module`, `default`), or else its `browser`, `module` or `main` field. Dependencies are bundled from `node_modules`, in the versions that their version ranges resolve to on that day. The banner records the exact versions.
+
+With `--entry` you choose a file inside the package, or a subpath that the package exports:
+
+```bash
+npx iifeify vanilla-jsoneditor --entry standalone.js
+npx iifeify rxjs --entry operators
+```
+
+Some packages ship a ready-made browser file with all dependencies already inside, like `standalone.js` above. Bundling that file gives the same output every time. When a package names such a file in its `browser` field but `exports` points elsewhere, iifeify prints a hint with the `--entry` to use.
+
+### The global
+
+- For an ES module package the global is an object with the package's exports. A default export is the property `default`.
+- For a CommonJS package the global is whatever the package assigns to `module.exports`.
+- If the package imports CSS, the styles are written next to the script, with `.css` in place of `.js`.
+- `process.env.NODE_ENV` is replaced by `"production"`.
+
+### License information
+
+The banner has one line for each package whose code is in the bundle: name, version, copyright notice, license and web address. With bundled dependencies it looks like this:
+
+```js
+/*!
+ * is-odd 3.0.1 - Copyright (c) 2015-present, Jon Schlinkert. - MIT License - https://github.com/jonschlinkert/is-odd
+ *
+ * Bundled dependencies:
+ * is-number 6.0.0 - Copyright (c) 2014-2018, Jon Schlinkert. - MIT License - https://github.com/jonschlinkert/is-number
+ */
+```
+
+- The license comes from the `license` field of `package.json`.
+- The copyright notice is the first one in the package's license file if the license is MIT, ISC or BSD. Otherwise it is the `author` from `package.json`, and it is left out if there is none.
+- The address is the `homepage`, else the repository, else the package's npm page.
+- License comments in the source files (`/*! ... */`, `@license`, `@preserve`) are kept at the end of the script.
+- `--notices` writes the complete license and notice files of all bundled packages to one text file next to the script. Use it when you have to ship the full license texts with your product.
+
+### Packages that cannot be converted
+
+iifeify fails, and writes nothing, when the package cannot be bundled for a browser:
+
+- It imports a Node.js built-in module such as `fs` or `path`. The message names the modules and the files that import them.
+- It has no entry point that browser code can import, for example a command-line tool or a package whose `exports` only allow `require`. Name a file with `--entry` if you know one that works.
+- It imports a file type other than JavaScript, JSON or CSS, such as an image, a font or WebAssembly.
+- It uses top-level `await`, which a classic script cannot do.
+
+A package passes this check and can still fail in the browser if it uses Node.js globals such as `process.argv` or `Buffer` without importing anything. iifeify does not look for that.
+
+---
+
+## 🧠 Requirements
+
+- **Node.js** ≥ 22, with npm
+
+---
+
+## 🏗 Example
+
+A Business Central control add-in loads classic scripts only, so a library such as [vanilla-jsoneditor](https://github.com/josdejong/svelte-jsoneditor) has to be one file that defines a global. The command at the top of this page generates that file. In the `controladdin` object, list it under `Scripts`:
+
+```al
+Scripts = 'vanilla-jsoneditor.iife.js';
+StartupScript = 'Startup.js';
+```
+
+The startup script then finds the library in the global `VanillaJsonEditor` and can call, for example, `VanillaJsonEditor.createJSONEditor(...)`.
+
+---
+
+## 🧩 Repository
+
+GitHub: [Florian-Noever/iifeify](https://github.com/Florian-Noever/iifeify)
+
+Bug reports and feature requests are welcome via [Issues](https://github.com/Florian-Noever/iifeify/issues).
+
+---
+
+## 🛠️ Developer Notes
+
+### Architecture
+
+Plain JavaScript modules, run by Node.js as they are: there is no build step, and the package ships `bin/` and `src/` unchanged.
+
+| Module | Purpose |
+| --- | --- |
+| `bin/cli.js` | The command line, parsed with [cac](https://github.com/cacjs/cac), and the summary it prints |
+| `src/convert.js` | One conversion from start to end, including the temporary folder |
+| `src/install.js` | Reading the package spec and running `npm install` |
+| `src/bundle.js` | The esbuild call, and the explanation when a package cannot be bundled |
+| `src/packages.js` | Which packages ended up in the bundle, and their metadata and license files |
+| `src/banner.js` | The banner and the notices file |
+
+### Build commands
+
+```bash
+npm ci                 # install exactly what package-lock.json pins
+
+npm run check-types    # tsc over the JavaScript and its JSDoc types
+npm run lint           # eslint, with no warning allowed
+npm test               # the offline tests
+npm run test:e2e       # tests that install real packages from the npm registry
+node bin/cli.js ms     # the tool, run from the checkout
+```
+
+**Install scripts are opt-in.** npm 11 runs a dependency's install script only when `allowScripts` in `package.json` approves it. esbuild's is approved. On Windows, the import rules of the linter need the Microsoft Visual C++ Redistributable, which most machines already have.
+
+### Tests
+
+Both suites use Node.js's own test runner. `npm test` runs offline: it bundles small packages written into a temporary `node_modules`, and runs the CLI without installing anything. `npm run test:e2e` converts `ms`, `is-odd` and `mkdirp` from the npm registry.
+
+### CI & Releases
+
+CI runs on every push and pull request. One job type-checks and lints, one runs both test suites on Linux with Node.js 22, 24 and 26 and on Windows with Node.js 24, and a third packs a preview tarball, kept for 14 days. Dependabot's minor and patch updates are merged once all three passed. `ci.yml` and `publish.yml` only call the shared npm package workflows of [Florian-Noever/Florian-Noever](https://github.com/Florian-Noever/Florian-Noever/blob/main/.github/CI.md), which hold the jobs.
+
+To release, bump the version with `npm version x.y.z --no-git-tag-version` and publish a GitHub release `vx.y.z` from a commit whose CI is green. The publish workflow checks, tests and packs the tag, attaches the tarball to the release with a build attestation, and publishes the same tarball to npm. A pre-release only gets the tarball on the GitHub release.
+
+npm publishes through a trusted publisher instead of a token, and adds provenance. npm only offers trusted publishers for a package that exists, so publish the first version from your machine with `npm publish`. Shortly before the next release, add one in the package's settings on [npmjs.com](https://www.npmjs.com): GitHub Actions, user `Florian-Noever`, repository `iifeify`, workflow `publish.yml`, environment `npm`. Allow `npm publish` for it as well, since a new trusted publisher only allows staged publishing otherwise. It expires unless it publishes within 48 hours. npm checks the name of this repository's `publish.yml`, not of the shared workflow it calls; see [Trusted publishing](https://github.com/Florian-Noever/Florian-Noever/blob/main/.github/CI.md#trusted-publishing) in the shared CI docs.
+
+---
+
+## 📜 License
+
+Licensed under the [MIT](LICENSE) License.
+
+<br>
+<br>
+
+[!["Buy me a coffee"](https://raw.githubusercontent.com/Florian-Noever/Florian-Noever/refs/heads/main/_meta/BuyMeACoffee/Buttons%20%26%20Icons/orange-button-x180.png)](https://www.buymeacoffee.com/florian_noever)

package/bin/cli.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { isAbsolute, relative } from 'node:path';
+import { cac } from 'cac';
+
+import { convert } from '../src/convert.js';
+import { ConversionError, UsageError } from '../src/errors.js';
+
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+
+// cac turns a value that looks like a number into one, such as the file name in "--outfile 2024".
+const text = value => (value === undefined ? undefined : String(value));
+
+const cli = cac('iifeify');
+
+cli.command('<package>', 'Turn an npm package into one classic browser script that defines a single global')
+    .usage('<package>[@version] [options]')
+    .option('-e, --entry <path>', 'File or subpath inside the package to bundle (default: its own browser entry)')
+    .option('-g, --global-name <name>', 'Global variable the script defines (default: the package name in PascalCase)')
+    .option('-o, --outfile <file>', 'Where to write the script (default: ./<package>.iife.js)')
+    .option('--minify', 'Minify the output; --no-minify keeps it readable', { default: true })
+    .option('--target <list>', 'Language level of the output, e.g. es2020 (default: esnext)')
+    .option('--notices', 'Also write the full license texts of all bundled packages, e.g. to ms.iife.LICENSES.txt')
+    .example('  $ iifeify ms')
+    .example('  $ iifeify vanilla-jsoneditor@3.13.0 --entry standalone.js --global-name VanillaJsonEditor')
+    .action(async (spec, options) => {
+        report(await convert({
+            spec: String(spec),
+            entry: text(options.entry),
+            globalName: text(options.globalName),
+            outfile: text(options.outfile),
+            minify: options.minify,
+            target: text(options.target)?.split(','),
+            notices: options.notices,
+        }));
+    });
+cli.help();
+cli.version(version);
+
+/** @param {Awaited<ReturnType<typeof convert>>} result */
+function report({ files, bytes, packages, entry, globalName, warnings, hint }) {
+    const [root, ...dependencies] = packages;
+    // Relative to the current folder if the file is inside it, else in full.
+    const shown = file => {
+        const fromHere = relative(process.cwd(), file);
+        return fromHere.startsWith('..') || isAbsolute(fromHere) ? file : fromHere;
+    };
+    const described = pkg => `${pkg.name} ${pkg.version} - ${pkg.license ?? 'license unknown'}`;
+    const size = bytes < 1024 * 1024 ? `${(bytes / 1024).toFixed(1)} KB` : `${(bytes / 1024 / 1024).toFixed(2)} MB`;
+
+    console.log(`Wrote ${shown(files.js)} (${size})`);
+    console.log(`  package  ${described(root)}`);
+    console.log(`  entry    ${entry}`);
+    console.log(`  global   ${globalName}`);
+    if (dependencies.length > 0) {
+        console.log(`  bundled  ${dependencies.length} ${dependencies.length === 1 ? 'dependency' : 'dependencies'}`);
+        for (const dependency of dependencies) {
+            console.log(`           ${described(dependency)}`);
+        }
+    }
+    if (files.css) {
+        console.log(`  styles   ${shown(files.css)}`);
+    }
+    if (files.notices) {
+        console.log(`  notices  ${shown(files.notices)}`);
+    }
+
+    for (const warning of warnings) {
+        console.error(`\n${warning}`);
+    }
+    if (hint) {
+        console.log(`\nHint: ${hint}`);
+    }
+}
+
+try {
+    // Parsing prints the help or the version if asked to. Running is a separate step, so that
+    // a failure inside the conversion can be awaited and caught here.
+    cli.parse(process.argv, { run: false });
+    await cli.runMatchedCommand();
+} catch (error) {
+    // cac does not export the class of the errors it throws for a wrong command line.
+    if (error instanceof UsageError || error.name === 'CACError') {
+        console.error(`${error.message}\nRun "iifeify --help" for the options.`);
+        process.exitCode = 2;
+    } else if (error instanceof ConversionError) {
+        console.error(error.message);
+        process.exitCode = 1;
+    } else {
+        console.error(error);
+        process.exitCode = 1;
+    }
+}

package/package.json

@@ -1,6 +1,64 @@
 {
-  "name": "iifeify",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "iifeify",
+    "version": "1.0.0",
+    "description": "Turn any browser-compatible npm package into a single classic script (an IIFE that defines one global), with a generated license banner.",
+    "license": "MIT",
+    "author": "Florian Noever",
+    "type": "module",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Florian-Noever/iifeify.git"
+    },
+    "bugs": {
+        "url": "https://github.com/Florian-Noever/iifeify/issues"
+    },
+    "homepage": "https://github.com/Florian-Noever/iifeify",
+    "keywords": [
+        "iife",
+        "bundle",
+        "esbuild",
+        "browser",
+        "script",
+        "global",
+        "license",
+        "cli",
+        "npx",
+        "al",
+        "business-central",
+        "control-addin"
+    ],
+    "bin": {
+        "iifeify": "bin/cli.js"
+    },
+    "engines": {
+        "node": ">=22"
+    },
+    "files": [
+        "bin",
+        "src"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "check-types": "tsc --noEmit",
+        "lint": "eslint --max-warnings 0",
+        "test": "node --test \"test/*.test.js\"",
+        "test:e2e": "node --test \"test/e2e/*.test.js\"",
+        "build:example": "node bin/cli.js vanilla-jsoneditor@3.13.0 --entry standalone.js --global-name VanillaJsonEditor --outfile examples/bc-json-viewer/vanilla-jsoneditor.iife.js"
+    },
+    "dependencies": {
+        "cac": "^7.1.0",
+        "esbuild": "^0.28.0"
+    },
+    "devDependencies": {
+        "@stylistic/eslint-plugin": "^5.10.0",
+        "@types/node": "^22.20.5",
+        "eslint": "^10.14.0",
+        "eslint-plugin-import-x": "^4.18.1",
+        "typescript": "^6.0.3"
+    },
+    "allowScripts": {
+        "esbuild": true
+    }
+}

package/src/banner.js

@@ -0,0 +1,64 @@
+const RULE = '='.repeat(80);
+
+/**
+ * The comment that opens the generated script: one line per bundled package.
+ *
+ * @param {object[]} packages   as described by describePackage, the converted package first
+ */
+export function renderBanner([root, ...dependencies]) {
+    if (dependencies.length === 0) {
+        return `/*! ${line(root)} */`;
+    }
+    return [
+        '/*!',
+        ` * ${line(root)}`,
+        ' *',
+        ' * Bundled dependencies:',
+        ...dependencies.map(dependency => ` * ${line(dependency)}`),
+        ' */',
+    ].join('\n');
+}
+
+function line({ name, version, copyright, license, url }) {
+    return [[name, version].filter(Boolean).join(' '), copyright, licenseLabel(license), url]
+        .filter(Boolean)
+        .map(clean)
+        .join(' - ');
+}
+
+function licenseLabel(license) {
+    if (!license) {
+        return 'license unknown';
+    }
+    // "MIT" reads better as "MIT License"; an expression such as "(MIT OR Apache-2.0)" stays as it is.
+    return /^[\w.+-]+$/.test(license) ? `${license} License` : license;
+}
+
+// The values come from package metadata, which anyone can publish: nothing in them may end the
+// comment or start a new line, or the rest would run as code.
+function clean(value) {
+    return String(value).replace(/\s+/g, ' ').replaceAll('*/', '* /').trim();
+}
+
+/**
+ * The text of the notices file: the full license texts of all bundled packages.
+ *
+ * @param {object[]} packages    as described by describePackage
+ * @param {string} scriptName    file name of the script the notices belong to
+ */
+export function renderNotices(packages, scriptName) {
+    const sections = packages.map(({ name, version, license, url, legalTexts }) => [
+        RULE,
+        [name, version].filter(Boolean).join(' '),
+        `License: ${license ?? 'unknown'}`,
+        url,
+        RULE,
+        '',
+        legalTexts.length > 0
+            ? legalTexts.map(({ text }) => text).join('\n\n')
+            : 'This package contains no license file.',
+        '',
+    ].join('\n'));
+
+    return [`License notices for the packages bundled in ${scriptName}`, '', ...sections].join('\n');
+}

package/src/bundle.js

@@ -0,0 +1,150 @@
+import { existsSync, statSync } from 'node:fs';
+import { isBuiltin } from 'node:module';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import * as esbuild from 'esbuild';
+
+import { ConversionError, UsageError } from './errors.js';
+
+// esbuild derives the names in its metafile from an output name. Nothing is written under it.
+const OUT_JS = 'out.js';
+
+const MAX_ERRORS_SHOWN = 10;
+const MESSAGE_FORMAT = { color: false, terminalWidth: 100 };
+
+/**
+ * Rejects a global name or target that esbuild will not accept. esbuild defines the rules for
+ * both, so it is asked directly. This is quick, so it can run before anything is installed.
+ *
+ * @param {{ globalName?: string, target?: string[] }} options
+ */
+export async function checkOptions({ globalName, target }) {
+    try {
+        await esbuild.transform('', { format: 'iife', globalName, target });
+    } catch (error) {
+        // A bad target fails with a message that names it. A bad global name fails like a syntax error in code.
+        if (!Array.isArray(error.errors)) {
+            throw new UsageError(error.message);
+        }
+        throw new UsageError(`--global-name "${globalName}" is not a valid name. ${error.errors.map(({ text }) => text).join(' ')}`);
+    }
+}
+
+/**
+ * Bundles an installed package into one classic script that defines a global.
+ *
+ * @param {object} options
+ * @param {string} options.workDir       folder whose node_modules holds the package
+ * @param {string} options.name          the package's folder name inside node_modules
+ * @param {string} options.dir           the package's folder
+ * @param {string} options.label         the package in messages, such as "ms 2.1.3"
+ * @param {string} [options.entry]       file or subpath inside the package; default is its browser entry
+ * @param {string} options.globalName
+ * @param {boolean} options.minify
+ * @param {string[]} [options.target]
+ * @returns {Promise<{ js: string, css?: string, entry: string, inputs: string[], warnings: string[] }>}
+ *     the script, the stylesheet if the package imports CSS, the entry file, the files whose code
+ *     is in the output (both as absolute paths), and esbuild's warnings as text
+ */
+export async function bundle({ workDir, name, dir, label, entry, globalName, minify, target }) {
+    const entryPoint = entryPointFor(name, dir, entry);
+
+    let result;
+    try {
+        result = await esbuild.build({
+            absWorkingDir: workDir,
+            entryPoints: [entryPoint],
+            outfile: OUT_JS,
+            write: false,
+            metafile: true,
+            bundle: true,
+            format: 'iife',
+            globalName,
+            // Makes an import of a Node built-in such as "fs" an error.
+            platform: 'browser',
+            minify,
+            target,
+            legalComments: 'eof',
+            // esbuild sets this by itself only when minifying.
+            define: { 'process.env.NODE_ENV': '"production"' },
+            logLevel: 'silent',
+        });
+    } catch (error) {
+        if (!Array.isArray(error.errors)) {
+            throw error;
+        }
+        throw new ConversionError(await explainFailure(error.errors, label, entryPoint, entry));
+    }
+
+    const { outputs } = result.metafile;
+    const inputs = new Set();
+    for (const output of Object.values(outputs)) {
+        for (const [file, { bytesInOutput }] of Object.entries(output.inputs)) {
+            if (bytesInOutput > 0) {
+                inputs.add(resolve(workDir, file));
+            }
+        }
+    }
+    const text = extension => result.outputFiles.find(file => file.path.endsWith(extension))?.text;
+
+    // A build that succeeds always has a script and an entry point.
+    return {
+        js: /** @type {string} */ (text('.js')),
+        css: text('.css'),
+        entry: resolve(workDir, /** @type {string} */ (outputs[OUT_JS].entryPoint)),
+        // A module that the package's "browser" field switches off is listed under a made-up path.
+        inputs: [...inputs].filter(existsSync),
+        warnings: await esbuild.formatMessages(result.warnings, { kind: 'warning', ...MESSAGE_FORMAT }),
+    };
+}
+
+/**
+ * What to hand esbuild as entry point: a file inside the package, or a package path. esbuild
+ * resolves a package path like an import in browser code: through "exports" with the conditions
+ * browser, import, module and default, else through the fields browser, module and main.
+ */
+function entryPointFor(name, dir, entry) {
+    if (!entry) {
+        return name;
+    }
+
+    const file = resolve(dir, entry);
+    const fromPackage = relative(dir, file);
+    if (fromPackage === '..' || fromPackage.startsWith(`..${sep}`) || isAbsolute(fromPackage)) {
+        throw new UsageError(`--entry must name something inside the package, got: ${entry}`);
+    }
+    if (!fromPackage) {
+        return name;
+    }
+    if (statSync(file, { throwIfNoEntry: false })?.isFile()) {
+        return file;
+    }
+    return `${name}/${fromPackage.replaceAll('\\', '/')}`; // a subpath from the package's "exports"
+}
+
+/** Says in one sentence why the package cannot be bundled, followed by esbuild's own messages. */
+async function explainFailure(errors, label, entryPoint, entry) {
+    const unresolved = errors.map(error => /^Could not resolve "(.+)"$/.exec(error.text)?.[1]).filter(Boolean);
+    const builtins = [...new Set(unresolved.filter(isBuiltin).map(module => module.replace(/^node:/, '')))].sort();
+
+    let summary;
+    if (builtins.length > 0) {
+        const modules = `module${builtins.length > 1 ? 's' : ''} ${builtins.join(', ')}`;
+        summary = `${label} is not browser compatible: it needs the Node.js built-in ${modules}.`;
+    } else if (unresolved.includes(entryPoint)) {
+        summary = entry
+            ? `${label} has no file or export "${entry}".`
+            : `${label} has no entry point that can be imported in a browser. Use --entry to name a file inside the package.`;
+    } else {
+        summary = `${label} could not be bundled for the browser.`;
+    }
+
+    // esbuild's notes also suggest options of its own, such as "You can use platform: 'node'".
+    // This tool has no such options, and none of them would make the package run in a browser.
+    const shown = errors.slice(0, MAX_ERRORS_SHOWN).map(error => ({
+        ...error,
+        notes: error.notes.filter(note => !/\bYou can (use|mark)\b/.test(note.text)),
+    }));
+    const details = await esbuild.formatMessages(shown, { kind: 'error', ...MESSAGE_FORMAT });
+    const more = errors.length > shown.length ? `...and ${errors.length - shown.length} more errors.` : '';
+    return `${summary}\n\n${details.join('')}${more}`.trimEnd();
+}

package/src/convert.js

@@ -0,0 +1,105 @@
+import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+
+import { renderBanner, renderNotices } from './banner.js';
+import { bundle, checkOptions } from './bundle.js';
+import { installPackage, parseSpec } from './install.js';
+import { bundledPackages } from './packages.js';
+
+/**
+ * Installs an npm package into a temporary folder and writes it as one classic browser script.
+ *
+ * @param {object} options
+ * @param {string} options.spec            package to convert, such as "vanilla-jsoneditor@3.13.0"
+ * @param {string} [options.entry]         file or subpath inside the package; default is its browser entry
+ * @param {string} [options.globalName]    default is the package name in PascalCase
+ * @param {string} [options.outfile]       default is <package name>.iife.js in the current folder
+ * @param {boolean} [options.minify]
+ * @param {string[]} [options.target]      esbuild targets such as ["es2020"]
+ * @param {boolean} [options.notices]      also write the full license texts next to the script
+ * @returns {Promise<{ files: { js: string, css?: string, notices?: string }, bytes: number,
+ *     packages: object[], entry: string, globalName: string, warnings: string[], hint?: string }>}
+ */
+export async function convert({ spec, entry, globalName: requestedGlobalName, outfile, minify = true, target, notices = false }) {
+    const wanted = parseSpec(spec);
+    await checkOptions({ globalName: requestedGlobalName, target });
+
+    // The real path: on Windows the temp folder can be given as a short 8.3 alias, and esbuild
+    // reports files by their real paths.
+    const workDir = realpathSync.native(mkdtempSync(join(tmpdir(), 'iifeify-')));
+    try {
+        const { dir, manifest } = installPackage(wanted, workDir);
+        const globalName = requestedGlobalName ?? defaultGlobalName(manifest.name);
+
+        const label = `${manifest.name} ${manifest.version}`;
+        const built = await bundle({ workDir, name: wanted.name, dir, label, entry, globalName, minify, target });
+        const packages = bundledPackages(built.inputs, dir);
+        const banner = renderBanner(packages);
+
+        const files = { js: resolve(outfile ?? defaultOutfile(manifest.name)) };
+        const base = files.js.replace(/\.js$/i, '');
+        const script = `${banner}\n${built.js}`;
+        mkdirSync(dirname(files.js), { recursive: true });
+        writeFileSync(files.js, script);
+        if (built.css !== undefined) {
+            files.css = `${base}.css`;
+            writeFileSync(files.css, `${banner}\n${built.css}`);
+        }
+        if (notices) {
+            files.notices = `${base}.LICENSES.txt`;
+            writeFileSync(files.notices, renderNotices(packages, basename(files.js)));
+        }
+
+        const unlicensed = packages.filter(pkg => !pkg.license).map(pkg => `${pkg.name} ${pkg.version} does not declare a license.`);
+        return {
+            files,
+            bytes: Buffer.byteLength(script),
+            packages,
+            entry: relative(dir, built.entry).replaceAll('\\', '/'),
+            globalName,
+            warnings: [...built.warnings.map(warning => warning.trim()), ...unlicensed],
+            hint: entry ? undefined : prebuiltHint(manifest, dir, built.entry),
+        };
+    } finally {
+        try {
+            rmSync(workDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+        } catch {
+            // A virus scanner can hold files open on Windows. A leftover temp folder must not turn
+            // a finished conversion into a failure, or hide the error that is already on its way.
+        }
+    }
+}
+
+/** "vanilla-jsoneditor" and "@scope/vanilla-jsoneditor" both give "VanillaJsoneditor". */
+export function defaultGlobalName(packageName) {
+    const words = unscoped(packageName).split(/[^A-Za-z0-9]+/).filter(Boolean);
+    const name = words.map(word => word[0].toUpperCase() + word.slice(1)).join('');
+    return /^[A-Za-z]/.test(name) ? name : `_${name}`;
+}
+
+/** "@scope/vanilla-jsoneditor" gives "vanilla-jsoneditor.iife.js". */
+export function defaultOutfile(packageName) {
+    return `${unscoped(packageName)}.iife.js`;
+}
+
+function unscoped(packageName) {
+    return packageName.slice(packageName.indexOf('/') + 1);
+}
+
+/**
+ * Some packages point "exports" at a file that needs its dependencies bundled in, and "browser" at
+ * a ready-made file that contains them. Bundlers follow "exports", so the ready-made file takes --entry.
+ */
+function prebuiltHint(manifest, dir, entryFile) {
+    if (typeof manifest.browser !== 'string') {
+        return undefined;
+    }
+
+    const prebuilt = resolve(dir, manifest.browser);
+    if (prebuilt === entryFile || !existsSync(prebuilt)) {
+        return undefined;
+    }
+    const entry = relative(dir, prebuilt).replaceAll('\\', '/');
+    return `${manifest.name} also ships a prebuilt browser file. To bundle that instead, add: --entry ${entry}`;
+}

package/src/errors.js

@@ -0,0 +1,5 @@
+/** A conversion that cannot succeed as asked. The CLI prints the message and exits with 1. */
+export class ConversionError extends Error {}
+
+/** A wrong command line. The CLI prints the message and exits with 2. */
+export class UsageError extends Error {}

package/src/install.js

@@ -0,0 +1,52 @@
+import { execSync } from 'node:child_process';
+import { readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { ConversionError, UsageError } from './errors.js';
+
+// npm's rule for package names, including old names with capital letters.
+const PACKAGE_NAME = /^(@[a-z0-9~-][a-z0-9._~-]*\/)?[a-z0-9~-][a-z0-9._~-]*$/i;
+
+const INSTALL = 'npm install --ignore-scripts --no-audit --no-fund --no-package-lock --loglevel=error';
+
+/**
+ * Splits what the user typed, such as "vanilla-jsoneditor@3.13.0" or "@scope/name", into the
+ * package name and the version, range or tag to install.
+ */
+export function parseSpec(spec) {
+    const at = spec.indexOf('@', 1); // an @ at position 0 starts a scope
+    const name = at === -1 ? spec : spec.slice(0, at);
+    const range = at === -1 ? '' : spec.slice(at + 1);
+    if (!PACKAGE_NAME.test(name)) {
+        throw new UsageError(
+            `"${spec}" is not a package name. ` +
+            'Expected a name such as vanilla-jsoneditor, optionally with a version: vanilla-jsoneditor@3.13.0'
+        );
+    }
+    return { name, range: range || 'latest' };
+}
+
+/**
+ * Installs the package and its dependencies into workDir/node_modules.
+ *
+ * @returns {{ dir: string, manifest: object }} the package's folder and its package.json
+ */
+export function installPackage({ name, range }, workDir) {
+    // A package.json of our own makes workDir the project root. Without one, npm installs into the
+    // nearest parent folder that has a package.json, and the temp folder lies inside the user
+    // profile. It also keeps the range off the command line: on Windows npm starts through cmd.exe,
+    // where the ^, < and > of a range mean something else.
+    writeFileSync(join(workDir, 'package.json'), JSON.stringify({ private: true, dependencies: { [name]: range } }));
+
+    try {
+        execSync(INSTALL, { cwd: workDir, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8', windowsHide: true });
+    } catch (error) {
+        const output = String(error.stderr ?? '').trim() || error.message;
+        throw new ConversionError(`Could not install ${name}@${range}.\n\n${output}`);
+    }
+
+    // The real path, because that is how esbuild reports the package's files: a linked local folder
+    // (name@file:/some/folder) is not under node_modules at all.
+    const dir = realpathSync.native(join(workDir, 'node_modules', name));
+    return { dir, manifest: JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) };
+}

package/src/packages.js

@@ -0,0 +1,160 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+const NODE_MODULES = '/node_modules/';
+const HOSTS = { github: 'github.com', gitlab: 'gitlab.com', bitbucket: 'bitbucket.org' };
+
+const LEGAL_FILE = /^(licen[cs]e|copying|notice)\b/i;
+const CODE_FILE = /\.([cm]?js|ts|json)$/i;
+
+// License files of these kinds open with the package's own copyright notice. An Apache or GPL file
+// instead holds a fill-in template or the notice of the license's publisher.
+const NOTICE_FIRST_LICENSE = /\b(MIT|ISC|0?BSD)\b/i;
+// "Copyright (c) <year> <copyright holders>", "Copyright [yyyy] [name of copyright owner]"
+const TEMPLATE = /[<[{]\s*(year|yyyy|name|owner|fullname|copyright holders?)\b/i;
+// Sentences of the license text itself, which can start a line where the text is wrapped.
+const PROSE = /^copyright\s+(holders?|owners?|notice|law|and)\b/i;
+
+/**
+ * The packages whose code is in the bundle: the converted package first, then the others by name.
+ *
+ * @param {string[]} inputs   absolute paths of the bundled files
+ * @param {string} rootDir    folder of the converted package
+ */
+export function bundledPackages(inputs, rootDir) {
+    const dirs = new Set(inputs.map(packageDirOf).filter(Boolean).map(dir => resolve(dir)));
+    dirs.delete(resolve(rootDir));
+
+    // The same version can be installed more than once, in nested node_modules folders.
+    const others = new Map();
+    for (const dir of dirs) {
+        const pkg = describePackage(dir);
+        others.set(`${pkg.name}@${pkg.version}`, pkg);
+    }
+    return [describePackage(rootDir), ...[...others.keys()].sort().map(key => others.get(key))];
+}
+
+/** The folder of the package that a file belongs to, or undefined if it belongs to none. */
+export function packageDirOf(file) {
+    const path = file.replaceAll('\\', '/');
+    const at = path.lastIndexOf(NODE_MODULES);
+    if (at !== -1) {
+        const [first, second] = path.slice(at + NODE_MODULES.length).split('/');
+        return path.slice(0, at + NODE_MODULES.length) + (first.startsWith('@') ? `${first}/${second}` : first);
+    }
+
+    // A linked local folder is not under node_modules. Its package.json is the nearest one with a
+    // name; a nested one such as dist/esm/package.json only sets the module type.
+    for (let dir = dirname(file); ; dir = dirname(dir)) {
+        if (isPackageRoot(dir)) {
+            return dir;
+        }
+        if (dirname(dir) === dir) {
+            return undefined;
+        }
+    }
+}
+
+function isPackageRoot(dir) {
+    try {
+        return typeof JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).name === 'string';
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * What the banner and the notices file say about a package.
+ *
+ * @returns {{ name: string, version: string, license?: string, copyright?: string, url: string,
+ *     legalTexts: { file: string, text: string }[] }}
+ */
+export function describePackage(dir) {
+    const manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+    const license = licenseOf(manifest);
+    const legalTexts = readdirSync(dir, { withFileTypes: true })
+        .filter(entry => entry.isFile() && LEGAL_FILE.test(entry.name) && !CODE_FILE.test(entry.name))
+        .map(entry => entry.name)
+        .sort()
+        .map(file => ({ file, text: readFileSync(join(dir, file), 'utf8').replace(/\r\n?/g, '\n').trim() }));
+
+    return {
+        name: manifest.name,
+        version: manifest.version,
+        license,
+        copyright: copyrightOf(license, legalTexts, manifest.author),
+        url: urlOf(manifest),
+        legalTexts,
+    };
+}
+
+function licenseOf({ license, licenses }) {
+    if (typeof license === 'string' && license) {
+        return license;
+    }
+    if (typeof license?.type === 'string') { // old form: { type, url }
+        return license.type;
+    }
+    if (Array.isArray(licenses)) { // old form: a list of the above
+        return licenses.map(entry => entry?.type ?? entry).filter(type => typeof type === 'string').join(' OR ') || undefined;
+    }
+    return undefined;
+}
+
+function copyrightOf(license, legalTexts, author) {
+    if (license && NOTICE_FIRST_LICENSE.test(license)) {
+        for (const { text } of legalTexts) {
+            const notice = copyrightNotice(text);
+            if (notice) {
+                return notice;
+            }
+        }
+    }
+    // "Jane Doe <jane@example.com> (https://example.com)" or { name, email, url }
+    const name = typeof author === 'string' ? author.replace(/\s*[<(].*$/, '') : author?.name;
+    return typeof name === 'string' && name.trim() ? `(c) ${name.trim()}` : undefined;
+}
+
+/** The first copyright notice in a license text, such as "Copyright (c) 2020 Jane Doe". */
+function copyrightNotice(text) {
+    // Without Markdown heading, quote, list and emphasis marks.
+    const lines = text.split('\n').map(line => line.replace(/^[\s#>*_-]+|[\s*_]+$/g, ''));
+    const start = lines.findIndex(line => /^(copyright\b|\(c\)|©)/i.test(line) && !TEMPLATE.test(line) && !PROSE.test(line));
+    if (start === -1) {
+        return undefined;
+    }
+
+    // A long list of holders runs on to the next line, leaving a comma at the end of this one.
+    let end = start;
+    while (lines[end].endsWith(',') && lines[end + 1]) {
+        end++;
+    }
+    return lines.slice(start, end + 1).join(' ').replace(/\s+/g, ' ');
+}
+
+function urlOf({ name, homepage, repository }) {
+    if (typeof homepage === 'string' && /^https?:\/\//.test(homepage)) {
+        return homepage;
+    }
+    return repositoryUrl(repository) ?? `https://www.npmjs.com/package/${name}`;
+}
+
+/** The web address of a package.json "repository", which can be a string or { url } in several notations. */
+function repositoryUrl(repository) {
+    const raw = typeof repository === 'string' ? repository : repository?.url;
+    if (typeof raw !== 'string') {
+        return undefined;
+    }
+
+    const short = /^(?:(github|gitlab|bitbucket):)?([\w.-]+\/[\w.-]+)$/.exec(raw); // "user/repo", "gitlab:user/repo"
+    if (short) {
+        return `https://${HOSTS[short[1] ?? 'github']}/${short[2]}`;
+    }
+
+    const url = raw
+        .replace(/^git\+/, '')
+        .replace(/^git@([^:/]+):/, 'https://$1/') // git@github.com:user/repo.git
+        .replace(/^(git|ssh):\/\/(git@)?/, 'https://')
+        .replace(/\.git(#.*)?$/, '');
+    return /^https?:\/\//.test(url) ? url : undefined;
+}