chore: keep changelog manual through v2.0.0, re-enable automation afterward

Author: jankarres

.github/workflows/ci.yml

@@ -43,6 +43,14 @@ jobs:
             - name: Build package
               run: pnpm run build
 
+            - name: Ensure bundled LAME binary
+              env:
+                  LAME_FORCE_DOWNLOAD: "1"
+              run: node ./scripts/install-lame.mjs
+
+            - name: Diagnose bundled LAME binary
+              run: node ./scripts/diagnose-lame.mjs
+
             - name: Run examples
               run: |
                   pnpm run example:wav-to-mp3

.github/workflows/prepare-release.yml

@@ -49,6 +49,16 @@ jobs:
       - name: Integration tests
         run: pnpm run test:integration
 
+      - name: Determine changelog mode
+        id: changelog
+        run: |
+          git fetch --tags --force >/dev/null 2>&1 || true
+          if git rev-parse "v2.0.0" >/dev/null 2>&1; then
+            echo "skip=0" >> "$GITHUB_OUTPUT"
+          else
+            echo "skip=1" >> "$GITHUB_OUTPUT"
+          fi
+
       - name: Configure git
         run: |
           git config user.name "github-actions[bot]"
@@ -58,6 +68,8 @@ jobs:
         id: version
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SKIP_CHANGELOG: ${{ steps.changelog.outputs.skip }}
         run: |
           set -eo pipefail
           pnpm run release:version > version.log 2>&1 || STATUS=$?

AI_AGENT_INSTRUCTIONS.md

@@ -115,7 +115,9 @@ You operate as a senior Node.js and TypeScript backend engineer focused on maint
 - `package.json` exports map `.` to the compiled bundle with typed entry points; adjust both ESM and CJS paths when restructuring.
 - Keep `files` whitelist minimal.
 - Update README examples when public API changes, ensuring both buffer and file workflows remain documented.
-- `CHANGELOG.md` is generated from Conventional Commits during the release workflow; do not edit it manually.
+- `CHANGELOG.md` is generated from Conventional Commits during the release workflow for releases after 2.0.0; that release was curated manually, so avoid regenerating it automatically.
+- The release helper `scripts/release-version.mjs` honors `SKIP_CHANGELOG=1` for manual runs (used when finalizing 2.0.0); do not set it for subsequent releases so Lerna can emit the changelog.
+- The CI release workflow automatically toggles `SKIP_CHANGELOG` based on whether tag `v2.0.0` exists; until that tag is present (i.e., while preparing the 2.0.0 release) the changelog is kept manual, and all later releases revert to Conventional Commits output.
 - Maintain parity between runtime behaviour and README option tables; treat the table as authoritative for user-facing docs.
 - Generated outputs (`dist/**`, `coverage/**`, `vendor/**`) must never be checked into source control manually.
 
@@ -128,6 +130,7 @@ You operate as a senior Node.js and TypeScript backend engineer focused on maint
 - Start with unit tests to capture expected behaviour, then adjust implementation, and finish by running the full test suite.
 - When modifying CLI behaviour, test on at least one supported platform or enhance integration tests with synthetic binaries.
 - Prefer extending existing classes and helpers over introducing new modules; if a new module is required, place it under `src/core` (runtime logic) or `src/internal` (supporting utilities).
-- Document behavioural changes in commit messages following Conventional Commit rules; the release tooling will derive `CHANGELOG.md` automatically.
-- Never edit `CHANGELOG.md` by hand; rely on the release workflow or explicit project tooling to populate it.
+- Document behavioural changes in commit messages following Conventional Commit rules so the release tooling can derive `CHANGELOG.md` for future releases.
+- Manual edits to `CHANGELOG.md` are only allowed for the 2.0.0 release; subsequent entries must come from the automated workflow.
 - After finishing any feature implementation, include in your final response a Conventional Commit-style message suggestion that downstream tooling can use.
+- When referencing Node.js types, import them explicitly (e.g. `import type { ProcessEnv } from "node:process";`) instead of relying on the `NodeJS.*` namespace to keep ESLint satisfied.

CHANGELOG.md

@@ -1,3 +1,40 @@
+## <small>2.0.0 (2025-11-09)</small>
+
+### Breaking Changes
+
+- Postinstall now auto-downloads a platform-specific LAME binary into `vendor/lame/<platform>-<arch>/`. Pipelines must permit the download step or configure `LAME_BINARY`, `LAME_SKIP_DOWNLOAD`, or `LAME_FORCE_DOWNLOAD` to control it (more details see `README.md`).
+- The minimum Node.js version is 20 and the library is published as an ESM-first package with explicit `exports`. CommonJS imports are still supported. Deep imports like `require("node-lame/lib/...")` are no longer supported.
+
+### Features
+
+- Introduced duplex streaming helpers (`createLameEncoderStream` / `createLameDecoderStream`) so audio can flow through stdin/stdout while progress events continue to fire ([#11](https://github.com/devowlio/node-lame/issues/11)).
+- `Lame#setBuffer` accepts `ArrayBuffer` and all typed arrays, automatically normalizing samples to the requested bit depth and endianness ([#33](https://github.com/devowlio/node-lame/issues/33)).
+- Broadened CLI option support: gapless playback controls, priority/disptime tuning, channel swapping, gain, decode delay trimming, VBR fine-tuning, verbosity toggles, and custom ID3 frames via `meta.custom`.
+- Exported `resolveBundledLameBinary` and `resolveLameBinary` so applications can inspect or override the binary chosen at runtime.
+
+### Improvements
+
+- `spawnLameProcess` now drives all CLI interaction, guaranteeing consistent progress parsing and normalized warning/error messages.
+- Temp files live under `join(tmpdir(), "node-lame")`, are created lazily, and are cleaned up automatically, even after failures.
+- Documentation now covers the installer environment variables, typed-array ingestion, gapless workflows, and streaming usage.
+
+### Tooling & Quality
+
+- Builds now originate from modern TypeScript sources compiled by `tsup` into dual ESM/CJS bundles with generated typings.
+- Vitest-based unit and integration suites stub binaries, simulate streaming backpressure, and assert option coverage.
+- The installer maintains a deterministic vendor layout, making binary resolution reproducible across platforms.
+- Introduced CI/CD pipelines that lint, type-check, run unit and integration suites, and gate release publishing so every change ships through the same automated path.
+
 ## <small>1.5.1 (2025-10-28)</small>
 
-All releases up to this version were created without a changelog. Please refer to the comment messages for details on changes.
+All releases up to this version were created **without** a changelog. Please refer to the comment messages for details on changes!
+
+**Summary of features in version 1.x:**
+
+- Promise-based Node.js wrapper for the native LAME CLI that can both encode WAV/MP1/MP2/MP3 sources to MP3 and decode MP3 files back to WAV while reporting progress through `getStatus()` and an `EventEmitter` (`progress`, `finish`, `error`).
+- Supports file- and buffer-based workflows for both inputs and outputs, including optional in-memory pipelines, configurable temp directories, and custom binary paths so projects can bundle their own LAME builds.
+- Provides raw PCM ingestion controls (sample frequency, bit width, signed/unsigned, endian toggles) and format hints (`mp2Input`, `mp3Input`) so the CLI can be tuned for atypical sources.
+- Exposes the majority of LAME’s encoding knobs: stereo/joint/mono modes, mono downmix (`to-mono`), block-size tweaks, ReplayGain detection, channel scaling, presets, CPU feature flags, quality ladders, and the full suite of bitrate strategies (constant, forced, average, variable with quality targets, and noise-shaping helpers).
+- Includes resampling plus low-pass/high-pass filter controls and ISO-compliance/reservoir toggles for shaping output to device requirements or archival specs.
+- Ships rich ID3 tooling that can embed titles, artists, albums, years, comments, tracks, genres, artwork, genre lists, padding, and ID3v1/v2 variants while allowing strict tag validation.
+- Publishes TypeScript typings alongside the compiled library and maintains a Mocha/Chai suite that exercises encode/decode happy paths, buffer handling, metadata arguments, and failure cases (bad files, invalid options, unexpected process exits).

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2017-2021, devowl.io GmbH and Jan Karres
+Copyright (c) 2017-2025, devowl.io GmbH and Jan Karres
 
 Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
 

package.json

@@ -2,7 +2,7 @@
   "name": "node-lame",
   "version": "1.5.1",
   "description": "LAME MP3 encoder for Node.js",
-  "homepage": "https://github.com/devowlio/node-lame",
+  "homepage": "https://www.npmjs.com/package/node-lame",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/devowlio/node-lame.git"
@@ -54,7 +54,7 @@
     "prepublishOnly": "pnpm run build",
     "prepare": "husky",
     "changelog": "conventional-changelog -p conventionalcommits -i CHANGELOG.md -s",
-    "release:version": "HUSKY=0 pnpm lerna version --yes --no-commit-hooks",
+    "release:version": "node ./scripts/release-version.mjs",
     "release:publish": "pnpm lerna publish from-git --yes --create-release github",
     "release": "pnpm run release:version && pnpm run release:publish"
   },
@@ -80,12 +80,15 @@
     "@typescript-eslint/parser": "~8.46.2",
     "@vitest/coverage-istanbul": "~4.0.4",
     "conventional-changelog-cli": "^5.0.0",
+    "conventional-changelog-conventionalcommits": "~9.1.0",
+    "conventional-recommended-bump": "~11.2.0",
     "eslint": "~9.38.0",
     "eslint-config-prettier": "~10.1.8",
     "globals": "~16.4.0",
     "husky": "~9.1.7",
     "lerna": "~9.0.0",
     "prettier": "~3.6.2",
+    "semver": "^7.7.3",
     "tsup": "~8.5.0",
     "tsx": "~4.20.6",
     "typescript": "~5.9.3",

pnpm-lock.yaml

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { platform } from "node:os";
+
+const {
+    resolveLameBinary,
+    resolveBundledLibraryDirectory,
+} = await import(new URL("../dist/index.cjs", import.meta.url));
+
+function logSection(title) {
+    console.log(`[lame-diagnostics] ${title}`);
+}
+
+const binaryPath = resolveLameBinary();
+logSection(`Resolved binary: ${binaryPath}`);
+
+try {
+    const stats = statSync(binaryPath);
+    logSection(
+        `File stats -> size=${stats.size} mode=${stats.mode.toString(8)} mtime=${stats.mtime.toISOString()}`,
+    );
+} catch (error) {
+    logSection(`stat() failed: ${error instanceof Error ? error.message : error}`);
+}
+
+const runCommand = (cmd, args) => {
+    const result = spawnSync(cmd, args, {
+        encoding: "utf-8",
+    });
+
+    logSection(
+        `${cmd} ${args.join(" ")} exited ${result.status} (signal: ${result.signal ?? "none"})`,
+    );
+
+    if (result.stdout) {
+        console.log(result.stdout.trim());
+    }
+
+    if (result.stderr) {
+        console.error(result.stderr.trim());
+    }
+};
+
+runCommand(binaryPath, ["--version"]);
+
+if (platform() === "linux") {
+    runCommand("ldd", [binaryPath]);
+}
+
+const libraryDir = resolveBundledLibraryDirectory();
+logSection(
+    `Bundled library directory: ${libraryDir ?? "not found (not expected on this platform?)"}`,
+);
+if (libraryDir && existsSync(libraryDir)) {
+    const entries = readdirSync(libraryDir);
+    if (entries.length === 0) {
+        logSection("Bundled library directory is empty");
+    } else {
+        logSection(
+            `Bundled libraries:\n${entries.map((entry) => ` - ${entry}`).join("\n")}`,
+        );
+    }
+}