@illumine/npm-diff 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 unbyte <i@shangyes.net>
+
+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/lib/index.cjs

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+'use strict';
+
+var extraTypings = require('@commander-js/extra-typings');
+var zx = require('zx');
+var path = require('path');
+var semver = require('semver');
+var tar = require('tar');
+var prompts = require('@inquirer/prompts');
+var promises = require('fs/promises');
+var unminify = require('@illumine/unminify');
+var oxfmt = require('oxfmt');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var semver__default = /*#__PURE__*/_interopDefault(semver);
+
+// src/error.ts
+var CliError = class extends Error {
+};
+
+// src/registry.ts
+var DEFAULT_REGISTRY = "https://registry.npmjs.org";
+var ABBREVIATED = "application/vnd.npm.install-v1+json";
+async function fetchPackument(pkg, registry) {
+  const url = `${registry.replace(/\/+$/, "")}/${pkg.replace("/", "%2F")}`;
+  let res;
+  try {
+    res = await fetch(url, { headers: { accept: ABBREVIATED } });
+  } catch (cause) {
+    throw new CliError(`Could not reach the npm registry: ${cause.message}`);
+  }
+  if (res.status === 404) {
+    throw new CliError(`Package '${pkg}' was not found on the npm registry.`);
+  }
+  if (!res.ok) {
+    throw new CliError(`The npm registry returned HTTP ${res.status} for '${pkg}'.`);
+  }
+  return await res.json();
+}
+function pickVersion(versions, message, exclude) {
+  const pool = exclude ? versions.filter((version) => version !== exclude) : versions;
+  return prompts.search({
+    message,
+    pageSize: 15,
+    source: async (term) => {
+      const matched = term ? pool.filter((version) => version.includes(term)) : pool;
+      return matched.map((version) => ({ name: version, value: version }));
+    }
+  });
+}
+function sortVersions(a, b) {
+  return semver__default.default.lt(a, b) ? [a, b] : [b, a];
+}
+var JS_FILES = "**/*.{js,cjs,mjs}";
+var FORMATTABLE_FILES = "**/*.{js,cjs,mjs,jsx,ts,cts,mts,tsx,css,html,htm,yaml,yml,json,jsonc,json5}";
+async function unminifyTree(dir) {
+  for (const file of await zx.glob(JS_FILES, { cwd: dir, absolute: true, dot: true })) {
+    const code = await promises.readFile(file, "utf8");
+    try {
+      await promises.writeFile(file, await unminify.unminify(code, { filename: path.basename(file) }));
+    } catch {
+    }
+  }
+}
+async function formatTree(dir) {
+  for (const file of await zx.glob(FORMATTABLE_FILES, { cwd: dir, absolute: true, dot: true })) {
+    const code = await promises.readFile(file, "utf8");
+    try {
+      const { code: formatted } = await oxfmt.format(path.basename(file), code, {
+        tabWidth: 2,
+        printWidth: 120
+      });
+      await promises.writeFile(file, formatted);
+    } catch {
+    }
+  }
+}
+var EXTENSION_ID = "moshfeu.compare-folders";
+async function ensureVscode() {
+  const code = await zx.which("code", { nothrow: true });
+  if (!code) {
+    throw new CliError(
+      "The VS Code CLI ('code') was not found on your PATH.\nInstall VS Code, then run the 'Shell Command: Install \\'code\\' command in PATH' command from its Command Palette."
+    );
+  }
+  const { stdout } = await zx.$`code --list-extensions`;
+  const installed = stdout.split("\n").map((line) => line.trim().toLowerCase());
+  if (installed.includes(EXTENSION_ID)) return;
+  const install = await prompts.confirm({
+    message: `The '${EXTENSION_ID}' extension is required but not installed. Install it now?`,
+    default: true
+  });
+  if (!install) {
+    throw new CliError(`Cannot continue without the '${EXTENSION_ID}' extension.`);
+  }
+  await zx.$({ stdio: "inherit" })`code --install-extension ${EXTENSION_ID}`;
+}
+async function launchDiff(left, right) {
+  await zx.$({
+    env: { ...process.env, COMPARE_FOLDERS: "DIFF" },
+    stdio: "inherit"
+  })`code --new-window --wait ${left} ${right}`;
+}
+
+// src/npm-diff.ts
+var NpmDiff = class {
+  constructor(pkg, registry = DEFAULT_REGISTRY) {
+    this.pkg = pkg;
+    this.registry = registry;
+  }
+  pkg;
+  registry;
+  packument;
+  workdir = zx.tmpdir("npmdiff-");
+  async run(specA, specB) {
+    await ensureVscode();
+    this.packument = await zx.spinner(
+      `Fetching '${this.pkg}' from npm\u2026`,
+      () => fetchPackument(this.pkg, this.registry)
+    );
+    const [left, right] = specA && specB ? sortVersions(this.resolve(specA), this.resolve(specB)) : await this.pickVersions(specA);
+    if (left === right) {
+      throw new CliError(`Both specs resolve to ${left} \u2014 there is nothing to diff.`);
+    }
+    try {
+      await this.prepare(left);
+      await this.prepare(right);
+      console.log(zx.chalk.green(`Opening VS Code to diff ${this.pkg} ${left} \u2194 ${right}`));
+      await launchDiff(path.join(this.workdir, left), path.join(this.workdir, right));
+      console.log(zx.chalk.dim("VS Code closed \u2014 cleaning up temporary files."));
+    } finally {
+      await zx.fs.remove(this.workdir);
+    }
+  }
+  /** Resolve a version or dist-tag into a concrete published version. */
+  resolve(spec) {
+    const { versions, "dist-tags": tags } = this.packument;
+    const resolved = tags[spec] ?? (versions[spec] ? spec : void 0);
+    if (!resolved) {
+      throw new CliError(`'${spec}' is not a published version or dist-tag of this package.`);
+    }
+    return resolved;
+  }
+  async pickVersions(existing) {
+    const versions = Object.keys(this.packument.versions).sort(semver__default.default.rcompare);
+    if (existing) {
+      const version = this.resolve(existing);
+      return sortVersions(
+        version,
+        await pickVersion(versions, `Compare ${version} against`, version)
+      );
+    }
+    const first = await pickVersion(versions, "Select the first version");
+    const second = await pickVersion(versions, "Select the second version", first);
+    return sortVersions(first, second);
+  }
+  async prepare(version) {
+    const label = `${this.pkg}@${version}`;
+    const dir = path.join(this.workdir, version);
+    await zx.fs.mkdirp(dir);
+    const tarball = await zx.spinner(`Downloading ${label}`, () => this.download(version, dir));
+    await zx.spinner(`Unpacking ${label}`, () => this.unpack(tarball, dir));
+    await zx.spinner(`Unminifying ${label}`, () => unminifyTree(dir));
+    await zx.spinner(`Formatting ${label}`, () => formatTree(dir));
+  }
+  async download(version, dir) {
+    const { stdout } = await zx.$`npm pack ${this.pkg}@${version} --registry ${this.registry} --pack-destination ${dir} --json`;
+    const [{ filename }] = JSON.parse(stdout);
+    return path.join(dir, filename);
+  }
+  async unpack(tarball, dir) {
+    await tar.extract({ file: tarball, cwd: dir, strip: 1 });
+    await zx.fs.remove(tarball);
+  }
+};
+
+// src/index.ts
+zx.$.verbose = false;
+var program = new extraTypings.Command();
+program.name("npmdiff").description("Diff two versions of an npm package in VS Code, unminified and formatted").argument("<pkgname>", "npm package name (scoped names supported)").argument("[spec-a]", "a version or dist-tag").argument("[spec-b]", "a version or dist-tag").option("--registry <url>", "npm registry to query", DEFAULT_REGISTRY).action(
+  (pkgname, specA, specB, options) => new NpmDiff(pkgname, options.registry).run(specA, specB)
+);
+program.parseAsync().catch((error) => {
+  if (error instanceof CliError) {
+    console.error(zx.chalk.red(error.message));
+  } else if (error instanceof Error && error.name === "ExitPromptError") {
+    console.error(zx.chalk.yellow("Aborted."));
+  } else {
+    console.error(error);
+  }
+  process.exit(1);
+});

package/lib/index.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+import { Command } from '@commander-js/extra-typings';
+import { $, chalk, tmpdir, spinner, fs, which, glob } from 'zx';
+import { join, basename } from 'path';
+import semver from 'semver';
+import { extract } from 'tar';
+import { confirm, search } from '@inquirer/prompts';
+import { readFile, writeFile } from 'fs/promises';
+import { unminify } from '@illumine/unminify';
+import { format } from 'oxfmt';
+
+// src/error.ts
+var CliError = class extends Error {
+};
+
+// src/registry.ts
+var DEFAULT_REGISTRY = "https://registry.npmjs.org";
+var ABBREVIATED = "application/vnd.npm.install-v1+json";
+async function fetchPackument(pkg, registry) {
+  const url = `${registry.replace(/\/+$/, "")}/${pkg.replace("/", "%2F")}`;
+  let res;
+  try {
+    res = await fetch(url, { headers: { accept: ABBREVIATED } });
+  } catch (cause) {
+    throw new CliError(`Could not reach the npm registry: ${cause.message}`);
+  }
+  if (res.status === 404) {
+    throw new CliError(`Package '${pkg}' was not found on the npm registry.`);
+  }
+  if (!res.ok) {
+    throw new CliError(`The npm registry returned HTTP ${res.status} for '${pkg}'.`);
+  }
+  return await res.json();
+}
+function pickVersion(versions, message, exclude) {
+  const pool = exclude ? versions.filter((version) => version !== exclude) : versions;
+  return search({
+    message,
+    pageSize: 15,
+    source: async (term) => {
+      const matched = term ? pool.filter((version) => version.includes(term)) : pool;
+      return matched.map((version) => ({ name: version, value: version }));
+    }
+  });
+}
+function sortVersions(a, b) {
+  return semver.lt(a, b) ? [a, b] : [b, a];
+}
+var JS_FILES = "**/*.{js,cjs,mjs}";
+var FORMATTABLE_FILES = "**/*.{js,cjs,mjs,jsx,ts,cts,mts,tsx,css,html,htm,yaml,yml,json,jsonc,json5}";
+async function unminifyTree(dir) {
+  for (const file of await glob(JS_FILES, { cwd: dir, absolute: true, dot: true })) {
+    const code = await readFile(file, "utf8");
+    try {
+      await writeFile(file, await unminify(code, { filename: basename(file) }));
+    } catch {
+    }
+  }
+}
+async function formatTree(dir) {
+  for (const file of await glob(FORMATTABLE_FILES, { cwd: dir, absolute: true, dot: true })) {
+    const code = await readFile(file, "utf8");
+    try {
+      const { code: formatted } = await format(basename(file), code, {
+        tabWidth: 2,
+        printWidth: 120
+      });
+      await writeFile(file, formatted);
+    } catch {
+    }
+  }
+}
+var EXTENSION_ID = "moshfeu.compare-folders";
+async function ensureVscode() {
+  const code = await which("code", { nothrow: true });
+  if (!code) {
+    throw new CliError(
+      "The VS Code CLI ('code') was not found on your PATH.\nInstall VS Code, then run the 'Shell Command: Install \\'code\\' command in PATH' command from its Command Palette."
+    );
+  }
+  const { stdout } = await $`code --list-extensions`;
+  const installed = stdout.split("\n").map((line) => line.trim().toLowerCase());
+  if (installed.includes(EXTENSION_ID)) return;
+  const install = await confirm({
+    message: `The '${EXTENSION_ID}' extension is required but not installed. Install it now?`,
+    default: true
+  });
+  if (!install) {
+    throw new CliError(`Cannot continue without the '${EXTENSION_ID}' extension.`);
+  }
+  await $({ stdio: "inherit" })`code --install-extension ${EXTENSION_ID}`;
+}
+async function launchDiff(left, right) {
+  await $({
+    env: { ...process.env, COMPARE_FOLDERS: "DIFF" },
+    stdio: "inherit"
+  })`code --new-window --wait ${left} ${right}`;
+}
+
+// src/npm-diff.ts
+var NpmDiff = class {
+  constructor(pkg, registry = DEFAULT_REGISTRY) {
+    this.pkg = pkg;
+    this.registry = registry;
+  }
+  pkg;
+  registry;
+  packument;
+  workdir = tmpdir("npmdiff-");
+  async run(specA, specB) {
+    await ensureVscode();
+    this.packument = await spinner(
+      `Fetching '${this.pkg}' from npm\u2026`,
+      () => fetchPackument(this.pkg, this.registry)
+    );
+    const [left, right] = specA && specB ? sortVersions(this.resolve(specA), this.resolve(specB)) : await this.pickVersions(specA);
+    if (left === right) {
+      throw new CliError(`Both specs resolve to ${left} \u2014 there is nothing to diff.`);
+    }
+    try {
+      await this.prepare(left);
+      await this.prepare(right);
+      console.log(chalk.green(`Opening VS Code to diff ${this.pkg} ${left} \u2194 ${right}`));
+      await launchDiff(join(this.workdir, left), join(this.workdir, right));
+      console.log(chalk.dim("VS Code closed \u2014 cleaning up temporary files."));
+    } finally {
+      await fs.remove(this.workdir);
+    }
+  }
+  /** Resolve a version or dist-tag into a concrete published version. */
+  resolve(spec) {
+    const { versions, "dist-tags": tags } = this.packument;
+    const resolved = tags[spec] ?? (versions[spec] ? spec : void 0);
+    if (!resolved) {
+      throw new CliError(`'${spec}' is not a published version or dist-tag of this package.`);
+    }
+    return resolved;
+  }
+  async pickVersions(existing) {
+    const versions = Object.keys(this.packument.versions).sort(semver.rcompare);
+    if (existing) {
+      const version = this.resolve(existing);
+      return sortVersions(
+        version,
+        await pickVersion(versions, `Compare ${version} against`, version)
+      );
+    }
+    const first = await pickVersion(versions, "Select the first version");
+    const second = await pickVersion(versions, "Select the second version", first);
+    return sortVersions(first, second);
+  }
+  async prepare(version) {
+    const label = `${this.pkg}@${version}`;
+    const dir = join(this.workdir, version);
+    await fs.mkdirp(dir);
+    const tarball = await spinner(`Downloading ${label}`, () => this.download(version, dir));
+    await spinner(`Unpacking ${label}`, () => this.unpack(tarball, dir));
+    await spinner(`Unminifying ${label}`, () => unminifyTree(dir));
+    await spinner(`Formatting ${label}`, () => formatTree(dir));
+  }
+  async download(version, dir) {
+    const { stdout } = await $`npm pack ${this.pkg}@${version} --registry ${this.registry} --pack-destination ${dir} --json`;
+    const [{ filename }] = JSON.parse(stdout);
+    return join(dir, filename);
+  }
+  async unpack(tarball, dir) {
+    await extract({ file: tarball, cwd: dir, strip: 1 });
+    await fs.remove(tarball);
+  }
+};
+
+// src/index.ts
+$.verbose = false;
+var program = new Command();
+program.name("npmdiff").description("Diff two versions of an npm package in VS Code, unminified and formatted").argument("<pkgname>", "npm package name (scoped names supported)").argument("[spec-a]", "a version or dist-tag").argument("[spec-b]", "a version or dist-tag").option("--registry <url>", "npm registry to query", DEFAULT_REGISTRY).action(
+  (pkgname, specA, specB, options) => new NpmDiff(pkgname, options.registry).run(specA, specB)
+);
+program.parseAsync().catch((error) => {
+  if (error instanceof CliError) {
+    console.error(chalk.red(error.message));
+  } else if (error instanceof Error && error.name === "ExitPromptError") {
+    console.error(chalk.yellow("Aborted."));
+  } else {
+    console.error(error);
+  }
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@illumine/npm-diff",
+  "version": "0.0.1",
+  "description": "Diff two versions of an npm package in VS Code, unminified and formatted",
+  "type": "module",
+  "bin": {
+    "npmdiff": "./lib/index.js"
+  },
+  "files": [
+    "lib"
+  ],
+  "keywords": [
+    "npm",
+    "diff",
+    "unminify",
+    "version",
+    "compare",
+    "vscode"
+  ],
+  "homepage": "https://github.com/unbyte/illumine/tree/main/packages/npm-diff#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unbyte/illumine.git",
+    "directory": "packages/npm-diff"
+  },
+  "bugs": {
+    "url": "https://github.com/unbyte/illumine/issues"
+  },
+  "author": {
+    "name": "unbyte",
+    "url": "https://github.com/unbyte"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@inquirer/prompts": "^8.5.2",
+    "@commander-js/extra-typings": "^15.0.0",
+    "commander": "^15.0.0",
+    "oxfmt": "~0.53.0",
+    "semver": "^7.8.5",
+    "tar": "^7.5.19",
+    "zx": "^8.8.5",
+    "@illumine/unminify": "0.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup"
+  }
+}