release: v2.0.3 - require the ESM entry directly, fail clearly on Node…

.github/workflows/bundle-size.yml

@@ -40,7 +40,7 @@ jobs:
         with:
             build_command: "npm run build:ci"
             # Every glob starts with `*`: the v4.29.2 measure action walks each path prefix separately (a bare top-level file matches nothing, and mixing `*` globs with directory globs counts files twice). CLDMV/.github#326/#327 fix this upstream.
-            dist_paths: "*index.mjs,*index.cjs,*devcheck.mjs,*dist/**,*types/index.d.mts*,*types/devcheck*.mts,*types/dist/**"
+            dist_paths: "*index.mjs,*index.cjs,*dist/**,*types/index.d.mts*,*types/dist/**"
             # warning_pct: 5
             # warning_bytes: 500
             # comment_mode: "update"

docs/changelog/v1/v1.1.1.md

@@ -0,0 +1,24 @@
+# DroidSock v1.1.1 Changelog
+
+**Release Date**: September 2026
+**Release Type**: Patch
+
+---
+
+## Overview
+
+v1.1.1 is a documentation-only release. **No runtime code changed**: the shipped `index.mjs`, `index.cjs` and `dist/` files are the same as in v1.1.0.
+
+---
+
+## 📚 Documentation
+
+### Pad slashes between adjacent code spans ([#15](https://github.com/CLDMV/droidsock/pull/15), release [#16](https://github.com/CLDMV/droidsock/pull/16))
+
+Runs of adjacent inline code spans separated by bare slashes (for example `` `mkdir`/`remove`/`move` ``) now have a space on each side of the slash (`` `mkdir` / `remove` / `move` ``) throughout `README.md`, `docs/API.md` and `docs/PROTOCOL.md`. Some Markdown renderers merge unpadded spans into one, which made the method lists hard to read. The wording and the documented API are unchanged.
+
+---
+
+## Upgrade notes
+
+- No breaking changes. This is a drop-in replacement for v1.1.0, and no runtime code changed.

docs/changelog/v2/v2.0.1.md

@@ -0,0 +1,76 @@
+# DroidSock v2.0.1 Changelog
+
+**Release Date**: October 2026
+**Release Type**: Patch
+
+---
+
+## Overview
+
+v2.0.1 is a maintenance release. **No runtime code changed**: `src/`, `index.mjs` and `index.cjs` are the same as in v2.0.0, so the API behaves exactly as before.
+
+The one change a consumer can see is the declared Node.js floor: `engines.node` rose from `>=20.19.0` to `>=22.12.0`, despite this being a patch release. It was raised to match the test toolchain (vitest 5), not because the library's own code needs a newer Node.js. See Breaking Changes below for who it affects.
+
+The rest of the release moves the test toolchain to vitest 5, syncs the CI and release workflows with the `CLDMV/.github` v4.29.2 templates, restores the verbatim Apache-2.0 license text, and makes the test suite more reliable under load.
+
+---
+
+## 💥 Breaking Changes
+
+### `engines.node` raised to `>=22.12.0` ([#38](https://github.com/CLDMV/droidsock/pull/38))
+
+The package's declared Node.js floor moved from `>=20.19.0` to `>=22.12.0` in a patch release. The library code did not change, so it still runs on Node.js 20.19 and later, but the declaration now excludes Node.js 20.19 to 22.11:
+
+- With npm's default settings, installing on those versions prints an `EBADENGINE` warning and continues.
+- With `engine-strict=true` (or a package manager configured to enforce `engines`), installing on those versions fails.
+
+**Upgrade step:** run on Node.js 22.12.0 or later. Projects that must stay on Node.js 20.19 to 22.11 can pin `@cldmv/droidsock@2.0.0`, which has the same runtime code.
+
+## 🔧 CI & tooling
+
+### Test toolchain moved to vitest 5 ([#36](https://github.com/CLDMV/droidsock/pull/36), [#38](https://github.com/CLDMV/droidsock/pull/38))
+
+`vitest` and `@vitest/coverage-v8` moved to 5.x together. vitest 5 needs Node.js `^22.12.0 || ^24.0.0 || >=26.0.0`, so the CI test matrix now runs from Node.js 22.12.0 up to 26.
+
+### Sync the v4 workflows with the CLDMV/.github v4.29.2 templates ([#46](https://github.com/CLDMV/droidsock/pull/46))
+
+Every workflow caller under `.github/workflows/` now matches the v4.29.2 templates. New callers are `release-merge.yml` (squash-merges the approved `next → master` release PR with its curated body as the commit message), `member-auto-merge.yml`, `dependabot-recreate.yml`, `provenance.yml` (SLSA build provenance for published releases), `pr-notify.yml` and `bundle-size.yml`, which reports how the published files change in size on each PR. The existing callers and `.github/dependabot.yml` were refreshed to the same template version. The same PR stops the bundle-size check from counting files twice.
+
+### Required PR Check no longer satisfied by a skipped run ([#50](https://github.com/CLDMV/droidsock/pull/50))
+
+On a PR from a branch in this repository, the `pull_request` run's copy of the `✅ Required PR Check` mirror job was skipped, because the push run reports the check for the same commit. GitHub counts a skipped job as passing for a required check, so a PR could look mergeable while its tests were still running. The skipped job now shows under a different name, so only the push run's result satisfies the ruleset.
+
+### Grouped Dependabot bumps ([#39](https://github.com/CLDMV/droidsock/pull/39))
+
+`vitest` + `@vitest/*`, the eslint family and the prettier family each bump in one grouped PR. These packages peer each other with major-locked ranges, so separate PRs broke `npm ci` with `ERESOLVE` whenever one moved without the others.
+
+### More reliable tests under load ([#48](https://github.com/CLDMV/droidsock/pull/48))
+
+A new Vitest setup file (`tests/setup/warm-droidsock.mjs`) composes and shuts down one droidsock instance before each test file is collected. The first instance in a file pays a one-time cold cost that was measured at 7 to 11 seconds on a busy machine, which raced the 10-second hook timeout and failed whichever test happened to run first. The device and connection tests also now assert against the real session instead of slothlet's mirror views.
+
+## 📄 License
+
+- `LICENSE` once again carries the verbatim Apache-2.0 text ([#45](https://github.com/CLDMV/droidsock/pull/45)). The license itself did not change.
+
+## 🔧 Dependencies
+
+Runtime:
+
+- `@cldmv/slothlet`: the lockfile moves from 3.15.0 to 3.20.0 (patch group bumps, including [#40](https://github.com/CLDMV/droidsock/pull/40)). The declared range stays `^3.15.0`, so consumers resolve whatever 3.x their own install picks.
+
+Dev-only:
+
+- `vitest` 4.1.11 → 5.0.2 and `@vitest/coverage-v8` 4.1.11 → 5.0.2 ([#36](https://github.com/CLDMV/droidsock/pull/36))
+- `@eslint/css` 1.4.0 → 2.0.0 ([#42](https://github.com/CLDMV/droidsock/pull/42))
+- `@types/node` 26.4.0 → 26.6.3, `eslint` 10.9.1 → 10.11.0, `@eslint/json` 2.0.1 → 2.1.0, `globals` 17.11.0 → 17.12.0, `prettier` 3.9.6 → 3.9.9, `@cldmv/fix-headers` 1.3.10 → 1.3.12, `@cldmv/jsonv` 1.0.2 → 1.0.9, `@cldmv/eslint-plugin-jsonv` 1.0.3 → 1.0.10 and `@cldmv/prettier-plugin-jsonv` 1.0.1 → 1.0.6 (grouped bumps [#32](https://github.com/CLDMV/droidsock/pull/32), [#33](https://github.com/CLDMV/droidsock/pull/33), [#41](https://github.com/CLDMV/droidsock/pull/41), [#43](https://github.com/CLDMV/droidsock/pull/43), [#44](https://github.com/CLDMV/droidsock/pull/44))
+
+## 📚 Documentation
+
+- **NEW:** [docs/changelog/v2/v2.0.1.md](./v2.0.1.md): this changelog, added after the release.
+
+---
+
+## Upgrade notes
+
+- The runtime code is identical to [v2.0.0](./v2.0.0.md).
+- Run on Node.js 22.12.0 or later to match the new `engines.node` declaration, or pin v2.0.0 if you need Node.js 20.19 to 22.11 with strict engine checks.

docs/changelog/v2/v2.0.2.md

@@ -0,0 +1,45 @@
+# DroidSock v2.0.2 Changelog
+
+**Release Date**: October 2026
+**Release Type**: Patch
+
+---
+
+## Overview
+
+v2.0.2 changes only development tooling and CI. **No runtime code changed**: the shipped `index.mjs`, `index.cjs` and `dist/` files differ from v2.0.1 only in their file-header comments, so the API behaves exactly as before.
+
+The release moves header maintenance onto the shared CLDMV `@cldmv/fix-headers` configuration, makes the required PR check report a real result on in-repo PRs, and brings in a set of dependency bumps.
+
+---
+
+## 🔧 CI & tooling
+
+### Shared fix-headers configuration ([#54](https://github.com/CLDMV/droidsock/pull/54))
+
+`npm run fix:headers` now runs the `fix-headers` CLI directly against a checked-in `.configs/fix-headers.json`, which extends `@cldmv/configs/fix-headers.json`. The local `tools/fix-headers.mjs` wrapper is gone. Running the shared config once rewrote the file headers across the repository into the uniform CLDMV format, which is why almost every file shows a header-only change in this release.
+
+### Run the in-repo PR mirror job instead of skipping it ([#55](https://github.com/CLDMV/droidsock/pull/55))
+
+v2.0.1 renamed the skipped copy of the `✅ Required PR Check` mirror job so it couldn't satisfy the ruleset. The job now always runs instead, and exits early with a note when the push run owns the status for that commit, so it never reports as skipped at all.
+
+## 🔧 Dependencies
+
+Runtime:
+
+- `@cldmv/slothlet`: the lockfile moves from 3.20.0 to 3.21.0 ([#57](https://github.com/CLDMV/droidsock/pull/57) / [#51](https://github.com/CLDMV/droidsock/pull/51)). The declared range stays `^3.15.0`.
+
+Dev-only:
+
+- `@cldmv/fix-headers` 1.3.12 → 2.1.2, plus `@cldmv/configs` 1.2.1 added for the shared config ([#54](https://github.com/CLDMV/droidsock/pull/54))
+- `@cldmv/vitest-runner` 1.2.0 → 1.5.1, `@cldmv/jsonv` 1.0.9 → 1.1.1, `@cldmv/prettier-plugin-jsonv` 1.0.6 → 1.1.0 and `@cldmv/eslint-plugin-jsonv` 1.0.10 → 1.0.13 (grouped bumps [#51](https://github.com/CLDMV/droidsock/pull/51), [#57](https://github.com/CLDMV/droidsock/pull/57))
+
+## 📚 Documentation
+
+- **NEW:** [docs/changelog/v2/v2.0.2.md](./v2.0.2.md): this changelog, added after the release.
+
+---
+
+## Upgrade notes
+
+- No breaking changes. This is a drop-in replacement for v2.0.1, and no runtime code changed.

docs/changelog/v2/v2.0.3.md

@@ -0,0 +1,60 @@
+# DroidSock v2.0.3 Changelog
+
+**Release Date**: October 2026
+**Release Type**: Patch
+**Branch**: `release/2.0.3`
+
+---
+
+## Overview
+
+v2.0.3 cleans up the CommonJS entry and the published file list. `index.cjs` now loads the ESM entry with a plain `require()`, which bundlers can follow, and fails with a clear message on Node.js versions that can't `require()` ES modules. The ESM entry and the API itself are unchanged.
+
+The release also stops publishing `devcheck.mjs`, a source-checkout-only development check, and removes its `./devcheck` subpath export. Removing an export is technically a breaking change despite this being a patch release, so it's listed under Breaking Changes below. In practice the module did nothing in an installed copy of the package.
+
+---
+
+## 💥 Breaking Changes
+
+### `@cldmv/droidsock/devcheck` is no longer exported or published ([#58](https://github.com/CLDMV/droidsock/pull/58))
+
+`package.json` no longer lists a `./devcheck` export, and `devcheck.mjs` and `types/devcheck.d.mts` are no longer in the published files. Importing `@cldmv/droidsock/devcheck` now fails with `ERR_PACKAGE_PATH_NOT_EXPORTED`.
+
+The module was never part of the documented API. It has no exports; its only job is to warn a developer working in a source checkout who forgot to set `NODE_OPTIONS=--conditions=droidsock-dev`. It only acts when a `src/` folder sits next to it, and the published package has no `src/`, so importing it from an installed copy did nothing. `index.mjs` still loads it fire-and-forget and already tolerates it being missing, so the main entry is unaffected.
+
+**Upgrade step:** if anything imports `@cldmv/droidsock/devcheck`, delete that import. Nothing replaces it, because it never did anything outside this repository.
+
+## 🐛 Bug Fixes
+
+### Require the ESM entry directly, and fail clearly without `require(esm)` ([#58](https://github.com/CLDMV/droidsock/pull/58))
+
+`index.cjs` used `createRequire(__filename)` to load `index.mjs`. That idiom predates Node's native `require(esm)`, and bundlers such as esbuild and webpack don't follow a `createRequire`-constructed `require` the way they follow a literal `require()` call, so a CommonJS build that bundled droidsock could miss the ESM entry.
+
+- `index.cjs` now calls `require("./index.mjs")` directly and exports the same functions as before (`module.exports` is the `droidsock` quick path, with `createDroidSock`, `DroidSock`, `ADB` and `AndroidDebugBridge` as properties).
+- On a Node.js version without `require(esm)` (before 20.19.0, or 22.0.0 to 22.11.x), `index.cjs` throws an `ERR_REQUIRE_ESM` error whose message names the supported versions and points to `import()`, instead of a bare loader error. The package's `engines.node` is already `>=22.12.0`, so this only matters for installs that ignore `engines`.
+- `index.mjs` already avoided top-level `await`, so it needed no change.
+- New `tests/cjs/entry.test.cjs` checks run under Node's own test runner after Vitest, from both `npm test` and `npm run coverage` (through the new `test:cjs` script). They check that `require()` returns the same functions as `import`, and that the version check fires when `require(esm)` is turned off. They don't call `droidsock()`, since that opens a real ADB connection.
+
+## 🔧 CI & tooling
+
+- `bundle-size.yml` no longer lists the `devcheck` files in `dist_paths`, matching the new published file list ([#58](https://github.com/CLDMV/droidsock/pull/58)).
+
+## 📚 Documentation
+
+- **NEW:** [docs/changelog/v2/v2.0.3.md](./v2.0.3.md): this changelog.
+- **NEW:** backfilled [v1.1.1](../v1/v1.1.1.md), [v2.0.1](./v2.0.1.md) and [v2.0.2](./v2.0.2.md).
+- README restructured to the standard CLDMV layout, with a new Requirements section that states the Node.js floor for `import` and `require()`.
+
+## 🔧 Dependencies
+
+Both changes are to development dependencies; the package has no runtime dependency changes and the published package is unaffected. Only `package.json` and the lockfile changed in these bumps, and no file headers were restamped.
+
+- `@cldmv/fix-headers` `^2.1.2` → `^2.2.0` ([#61](https://github.com/CLDMV/droidsock/pull/61) took it to `^2.1.4`, [#63](https://github.com/CLDMV/droidsock/pull/63) to `^2.2.0`). Version 2.1.4 no longer writes a JavaScript comment into JSON or Markdown files, processes every repeated `--input`, and never walks dependency folders such as `node_modules`. Version 2.2.0 makes the `@Last modified by` header tag follow content edits only, so a header-only rewrite keeps the recorded editor instead of replacing it. It requires Node.js `>=22.12.0`, which matches the package's `engines.node`.
+- `@cldmv/configs` `^1.2.1` → `^1.2.4` ([#63](https://github.com/CLDMV/droidsock/pull/63)). It provides the shared `fix-headers` configuration that `.configs/fix-headers.json` extends. Version 1.2.4 turns off `forceAuthorUpdate` and `forceLastModifiedAuthorUpdate` (both were on in 1.2.1), so the shared configuration no longer overwrites the recorded author or last editor.
+
+---
+
+## Upgrade notes
+
+- If anything imports `@cldmv/droidsock/devcheck`, remove that import. Nothing else needs to change.
+- `import droidsock from "@cldmv/droidsock"` and `require("@cldmv/droidsock")` both work as before on Node.js 22.12.0 or later.

index.cjs

@@ -21,11 +21,20 @@
  *
  * @module droidsock
  */
+"use strict";
 
-const { createRequire } = require("module");
-const requireESM = createRequire(__filename);
+// index.cjs is a thin wrapper: it loads index.mjs through Node's synchronous require(esm).
+// Node.js versions without require(esm) would fail with a bare ERR_REQUIRE_ESM, so fail
+// early with a message that says what to do instead.
+if (!process.features?.require_module) {
+	const error = new Error(
+		`@cldmv/droidsock: require() needs Node.js ^20.19.0 or >=22.12.0 (this is ${process.version}). On older Node.js, load the package with import() instead.`
+	);
+	error.code = "ERR_REQUIRE_ESM";
+	throw error;
+}
 
-const { default: droidsock } = requireESM("./index.mjs");
+const { default: droidsock } = require("./index.mjs");
 
 // Export main function - the quick path, also callable with options
 module.exports = droidsock; // Default export

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cldmv/droidsock",
-	"version": "2.0.2",
+	"version": "2.0.3",
 	"description": "Complete Node.js implementation of the Android Debug Bridge (ADB) protocol",
 	"main": "./index.cjs",
 	"module": "./index.mjs",
@@ -11,10 +11,6 @@
 			"import": "./index.mjs",
 			"require": "./index.cjs"
 		},
-		"./devcheck": {
-			"types": "./types/devcheck.d.mts",
-			"import": "./devcheck.mjs"
-		},
 		"./main": {
 			"droidsock-dev": {
 				"types": "./types/src/droidsock.d.mts",
@@ -32,10 +28,11 @@
 		"build": "node build.mjs",
 		"build:types": "tsc --project .configs/tsconfig.dts.jsonc",
 		"build:ci": "npm run build && npm run build:types && npm run test:types",
-		"test": "node tests/run-vitest.mjs",
+		"test": "node tests/run-vitest.mjs && npm run test:cjs",
+		"test:cjs": "CI=1 node --test tests/cjs/entry.test.cjs",
 		"test:watch": "vitest --config .configs/vitest.config.mjs",
 		"test:types": "tsc --noEmit --project .configs/tsconfig.dts.jsonc",
-		"coverage": "node tests/run-vitest.mjs --coverage-quiet",
+		"coverage": "node tests/run-vitest.mjs --coverage-quiet && npm run test:cjs",
 		"ci:coverage": "npm run coverage",
 		"lint": "eslint --config .configs/eslint.config.mjs .",
 		"lint:fix": "eslint --config .configs/eslint.config.mjs . --fix",
@@ -94,20 +91,18 @@
 	"files": [
 		"index.mjs",
 		"index.cjs",
-		"devcheck.mjs",
 		"README.md",
 		"LICENSE",
 		"types/dist/",
 		"types/index.d.mts",
 		"types/index.d.mts.map",
-		"types/devcheck.d.mts",
 		"dist/"
 	],
 	"sideEffects": false,
 	"devDependencies": {
-		"@cldmv/configs": "^1.2.1",
+		"@cldmv/configs": "^1.2.4",
 		"@cldmv/eslint-plugin-jsonv": "^1.0.3",
-		"@cldmv/fix-headers": "^2.1.2",
+		"@cldmv/fix-headers": "^2.2.0",
 		"@cldmv/jsonv": "^1.0.2",
 		"@cldmv/prettier-plugin-jsonv": "^1.0.1",
 		"@cldmv/vitest-runner": "^1.2.0",