@medyll/monorepo-pnpm-release 1.0.17

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 medyll
+
+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

@@ -0,0 +1,172 @@
+
+---
+
+# @medyll/monorepo-pnpm-release 🤖
+
+A lightweight, automated release manager for **pnpm workspaces**. It handles versioning, changelog generation, and publishing directly from GitHub Actions, for monorepos or standalone projects.
+
+## ✨ Features
+
+* **Directory-based Detection**: Only bumps packages that have actual changes in their folder.
+* **Independent Versioning**: Each package follows its own lifecycle.
+* **Smart Changelogs**: Injects updates into existing `CHANGELOG.md` while preserving history.
+* **Conventional Commits**: Automatically calculates `patch`, `minor`, or `major` bumps.
+* **Zero-Config CI**: Automatically handles Git identity (bot) if not configured.
+* **Hybrid Support**: Works perfectly for both large monorepos and single-package projects.
+
+---
+
+## 🚀 Installation & Usage
+
+## CLI Options
+
+### `--build`
+Execute the `build` script in each changed package before releasing. If a package does not define a `build` script, it is skipped with a neutral info message.
+
+```bash
+# Build changed packages only
+npx @medyll/monorepo-pnpm-release --build
+```
+
+### `--package`
+Execute the `package` script in each changed package before releasing. If a package does not define a `package` script, it is skipped with a neutral info message.
+
+```bash
+# Package changed packages only
+npx @medyll/monorepo-pnpm-release --package
+
+# Combine both flags
+npx @medyll/monorepo-pnpm-release --build --package
+```
+
+### `--verbose`
+Enable verbose logging with detailed output during the release process. Useful for debugging or understanding command execution.
+
+```bash
+npx @medyll/monorepo-pnpm-release --build all --verbose
+```
+
+### `--dry-run`
+Analyze and simulate the release without making any changes.
+
+```bash
+npx @medyll/monorepo-pnpm-release --dry-run
+```
+
+### Option A: One-time execution (npx)
+
+Useful to avoid polluting your dependencies.
+
+```bash
+npx @medyll/monorepo-pnpm-release
+
+```
+
+### Option B: Integrated dependency
+
+Recommended to lock the tool version for the whole team.
+
+```bash
+pnpm add -D @medyll/monorepo-pnpm-release
+
+```
+
+Then add the following script to `package.json` :
+
+```json
+"scripts": {
+  "release": "monorepo-pnpm-release"
+}
+
+```
+
+*Usage: `pnpm release*`
+
+---
+
+## 🛠 Workflow Integration
+
+Create the file `.github/workflows/release.yml` :
+
+```yaml
+name: Release
+on:
+  push:
+    branches: [main, develop]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 
+      
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: 'https://registry.npmjs.org'
+
+      - run: pnpm install --frozen-lockfile
+      - run: npx @medyll/monorepo-pnpm-release
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+```
+
+---
+
+## 📖 CLI Options
+
+| Option | Alias | Description | Default |
+| --- | --- | --- | --- |
+| `--dry-run` | `-d` | Simulates the release without modifying Git or NPM | `false` |
+| `--pre-id` | `-p` | Pre-release identifier (alpha, beta, next) | `alpha` |
+| `--verbose` | `-v` | Shows detailed logs of internal steps | `false` |
+| `--package` | `-k` | Runs `package` script in each changed package | `false` |
+| `--build` | `-b` | Runs `build` script in each changed package | `false` |
+
+---
+
+## 📝 Commit Convention
+
+The tool analyzes your commit messages to decide the next bump:
+
+* `fix: ...` → **patch**
+* `feat: ...` → **minor**
+* `feat!: ...` or `BREAKING CHANGE:` → **major**
+
+---
+
+## 🛠 Troubleshooting
+
+### NPM Authentication Issues
+
+If the CI fails at the `publish` step:
+
+1. **Token Type**: Use an **Automation** token (not Fine-grained without write permissions).
+2. **GitHub Secret**: Make sure the secret is named `NPM_TOKEN`.
+3. **Access**: For `@scope/` packages, ensure they are public:
+```json
+"publishConfig": { "access": "public" }
+
+```
+
+
+### Git Identity Error
+
+If you see `Author identity unknown`:
+The tool automatically configures `github-actions[bot]`. If you use your own identity, make sure it is set before running the tool.
+
+---
+
+## 📄 License
+
+MIT
+
+---

package/bin/cli.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { executeRelease } from '../src/index.js';
+
+const program = new Command();
+
+program
+  .name('@medyll/monorepo-pnpm-release')
+  .description('Automated release tool for pnpm workspaces and single packages')
+  .version('1.0.0')
+  .option('-d, --dry-run', 'Analyze and simulate the release without any side effects', false)
+  .option('-p, --pre-id <id>', 'Identifier for pre-release (e.g. alpha, beta, next)', 'alpha')
+  .option('-v, --verbose', 'Print detailed logs', false)
+  .option('-b, --build', 'Execute "pnpm run build" in each changed package before release', false)
+  .option('-k, --package', 'Execute "pnpm run package" in each changed package before release', false)
+  .action(async (options) => {
+    try { 
+      await executeRelease(options);
+    } catch (error) {
+      console.error(`\n❌ Execution failed: ${error.message}`);
+      process.exit(1);
+    }
+  });
+
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@medyll/monorepo-pnpm-release",
+  "version": "1.0.17",
+  "description": "Minimalist monorepo release tool for pnpm workspaces",
+  "type": "module",
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "bin": {
+    "monorepo-pnpm-release": "./bin/cli.js"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md"
+  ],
+  "keywords": [
+    "pnpm",
+    "monorepo",
+    "release",
+    "versioning",
+    "changelog"
+  ],
+  "author": "Mydde",
+  "license": "MIT",
+  "packageConfig": {
+    "access": "public",
+    "name": "@medyll/monorepo-pnpm-release",
+    "directory": "."
+  },
+  "dependencies": {
+    "@pnpm/find-workspace-packages": "^6.0.9",
+    "commander": "^14.0.3",
+    "conventional-commits-parser": "^6.2.1",
+    "execa": "^9.6.1",
+    "semver": "^7.7.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.1.0",
+    "@types/semver": "^7.7.1",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "start": "node bin/cli.js",
+    "release": "node bin/cli.js",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "check-types": "tsc --noEmit"
+  }
+}

package/src/changelog.js

@@ -0,0 +1,23 @@
+// author : Lebrun Meddy
+import fs from 'fs/promises';
+import path from 'path';
+
+export async function updateChangelog(pkg, { verbose } = {}) {
+  const file = path.join(pkg.dir, 'CHANGELOG.md');
+  let content = '';
+  try {
+    content = await fs.readFile(file, 'utf-8');
+    if (verbose) console.log(`[verbose] Read existing changelog for ${pkg.name}`);
+  } catch {
+    content = '# Changelog\n';
+    if (verbose) console.log(`[verbose] No existing changelog for ${pkg.name}, creating new.`);
+  }
+
+  const newEntry = `## [${pkg.newVersion}] - ${new Date().toISOString().split('T')[0]}\n- Update dependencies and fixes.\n`;
+  if (verbose) console.log(`[verbose] Adding changelog entry for ${pkg.name}:`, newEntry);
+  // Insert after the first H1
+  const lines = content.split('\n');
+  lines.splice(1, 0, '\n' + newEntry);
+  await fs.writeFile(file, lines.join('\n'));
+  if (verbose) console.log(`[verbose] Wrote changelog for ${pkg.name}`);
+}

package/src/detector.js

@@ -0,0 +1,95 @@
+// author : Lebrun Meddy
+import findWorkspacePackages from '@pnpm/find-workspace-packages';
+import { execa } from 'execa';
+import fs from 'fs/promises';
+import path from 'path';
+
+/**
+ * Get the most recent git tag for a specific package
+ */
+async function getLastTag(packageName) {
+  try {
+    const { stdout } = await execa('git', [
+      'describe',
+      '--tags',
+      '--match', `${packageName}@*`,
+      '--abbrev=0'
+    ]);
+    return stdout;
+  } catch {
+    // Fallback for single packages or missing tags
+    return null;
+  }
+}
+
+/**
+ * Identify which packages need a release
+ * Works for both pnpm workspaces and single packages
+ */
+export async function analyzeChanges({ verbose } = {}) {
+  let allPackages = [];
+  if (verbose) console.log('[verbose] Detecting workspace packages...');
+
+  try {
+    // Robust import handling for pnpm's internal tool
+    const getPkgs = typeof findWorkspacePackages === 'function' 
+      ? findWorkspacePackages 
+      : findWorkspacePackages.default;
+
+    allPackages = await getPkgs('.')
+    if (verbose) console.log('[verbose] Found packages:', allPackages.map(p => p.manifest?.name || p.dir));
+    // If workspace detection returns nothing, force fallback
+    if (!allPackages || allPackages.length === 0) {
+      throw new Error('No workspace found');
+    }
+  } catch (e) {
+    // Fallback: Check if the current directory is a standard pnpm package
+    const manifestPath = path.join(process.cwd(), 'package.json');
+    try {
+      const content = await fs.readFile(manifestPath, 'utf-8');
+      const manifest = JSON.parse(content);
+      
+      // We wrap the single package in the same structure as a workspace result
+      allPackages = [{
+        dir: process.cwd(),
+        manifest: manifest
+      }];
+    } catch (err) {
+      if (verbose) console.log('[verbose] No pnpm workspace or package.json found in this directory.');
+      console.error("❌ No pnpm workspace or package.json found in this directory.");
+      return [];
+    }
+  }
+
+  const packagesToRelease = [];
+
+  for (const pkg of allPackages) {
+    if (verbose) console.log(`[verbose] Checking package: ${pkg.manifest.name}`);
+    // Skip private packages unless they are the root fallback
+    if (pkg.manifest.private && allPackages.length > 1) continue;
+
+    const lastTag = await getLastTag(pkg.manifest.name);
+    const range = lastTag ? `${lastTag}..HEAD` : 'HEAD';
+    if (verbose) console.log(`[verbose] Using git range: ${range}`);
+
+    // Get logs for the package directory
+    // pkg.dir is absolute path, works for both workspace and root
+    const { stdout } = await execa('git', ['log', range, '--format=%B', '--', pkg.dir]);
+    if (verbose) console.log(`[verbose] Git log for ${pkg.manifest.name}:`, stdout);
+
+    // Split commits by double newline to separate them properly
+    const commits = stdout.split('\n').filter(Boolean);
+
+    if (commits.length > 0) {
+      packagesToRelease.push({
+        name: pkg.manifest.name,
+        dir: pkg.dir,
+        currentVersion: pkg.manifest.version,
+        rawCommits: commits
+      });
+      if (verbose) console.log(`[verbose] Package ${pkg.manifest.name} scheduled for release.`);
+    }
+  }
+  
+  return packagesToRelease;
+}

package/src/git.js

@@ -0,0 +1,41 @@
+// Commits & Tags multiples
+import { execa } from 'execa';
+// author : Lebrun Meddy
+
+/**
+ * Check if git user is configured, otherwise set a default bot identity
+ */
+async function ensureGitIdentity(verbose) {
+  try {
+    await execa('git', ['config', 'user.name']);
+    if (verbose) console.log('[verbose] Git user.name is set.');
+  } catch {
+    console.log("🔧 No git identity found. Setting default bot identity...");
+    if (verbose) console.log('[verbose] Would set git user.name and user.email to github-actions[bot]');
+    /* await execa('git', ['config', 'user.name', 'github-actions[bot]']);
+    await execa('git', ['config', 'user.email', 'github-actions[bot]@users.noreply.github.com']); */
+  }
+}
+
+export async function finalizeGit(releasedPackages, { verbose } = {}) {
+  // Check and set identity if needed
+  await ensureGitIdentity(verbose);
+  if (verbose) console.log('[verbose] Staging all changes for commit.');
+  await execa('git', ['add', '.']);
+
+  const commitMessage = `chore(release): publish packages\n\n${releasedPackages
+    .map(p => `- ${p.name}@${p.newVersion}`)
+    .join('\n')}`;
+  if (verbose) console.log('[verbose] Commit message:', commitMessage);
+  await execa('git', ['commit', '-m', commitMessage]);
+
+  for (const pkg of releasedPackages) {
+    const tagName = `${pkg.name}@${pkg.newVersion}`;
+    if (verbose) console.log(`[verbose] Tagging ${tagName}`);
+    // -f (force) prevents crashing if the tag was locally created before
+    await execa('git', ['tag', '-a', tagName, '-m', tagName, '-f']);
+  }
+
+  if (verbose) console.log('[verbose] Pushing tags and commits to origin.');
+  await execa('git', ['push', 'origin', '--follow-tags']);
+}

package/src/index.js

@@ -0,0 +1,94 @@
+// author : Lebrun Meddy
+import { analyzeChanges } from "./detector.js";
+import { bumpPackages } from "./versioner.js";
+import { updateChangelog } from "./changelog.js";
+import { finalizeGit } from "./git.js";
+import { publishToRegistry } from "./publisher.js";
+import { executePrePublishCommands } from "./pre-publish.js";
+
+// Simple verbose logger
+function vLog(verbose, ...args) {
+  if (verbose) {
+    console.log(`${"\x1b[90m"}[verbose]`, ...args, "\x1b[0m");
+  }
+}
+
+// ANSI Color codes
+const colors = {
+  reset: "\x1b[0m",
+  bright: "\x1b[1m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  magenta: "\x1b[35m",
+  cyan: "\x1b[36m",
+  red: "\x1b[31m",
+};
+
+export async function executeRelease(options) {
+  const isPre = process.env.GITHUB_REF !== "refs/heads/main";
+  const mode = isPre ? `PRE-RELEASE (${options.preId})` : "STABLE";
+  const verbose = options.verbose;
+
+  console.log(
+    `\n${colors.bright}${colors.blue}🚀 Starting release process in ${mode} mode...${colors.reset}\n`,
+  );
+  vLog(verbose, "Options:", options);
+
+  // 1. Detection
+  console.log(`${colors.cyan}🔍 Analyzing changes...${colors.reset}`);
+  const changes = await analyzeChanges({ verbose });
+
+  if (!changes.length) {
+    console.log(
+      `${colors.yellow}✨ Nothing to release. All packages are up to date.${colors.reset}`,
+    );
+    return;
+  }
+
+  console.log(
+    `${colors.green}Found ${changes.length} package(s) with changes.${colors.reset}`,
+  );
+
+  // 2. Pre-publish commands (per package)
+  await executePrePublishCommands(changes, options);
+
+  // 3. Bumping versions
+  console.log(`${colors.cyan}🆙 Bumping versions...${colors.reset}`);
+  const released = await bumpPackages(changes, isPre, options.preId, { verbose });
+
+  for (const pkg of released) {
+    console.log(
+      `  - ${colors.bright}${pkg.name}${colors.reset}: ${colors.yellow}${pkg.currentVersion}${colors.reset} -> ${colors.green}${pkg.newVersion}${colors.reset}`,
+    );
+    
+    // 3. Changelogs
+    console.log(`  - ${colors.blue}📝 Updating CHANGELOG.md...${colors.reset}`);
+    await updateChangelog(pkg, { verbose });
+
+  }
+
+  // 5. Execution or Dry Run
+  if (!options.dryRun) {
+    console.log(
+      `\n${colors.magenta}📂 Finalizing Git operations (commit & tags)...${colors.reset}`,
+    );
+    await finalizeGit(released, { verbose });
+
+    console.log(`${colors.magenta}📦 Publishing to registry...${colors.reset}`);
+    await publishToRegistry(released, isPre ? options.preId : "latest", {
+      verbose,
+    });
+
+    console.log(
+      `\n${colors.bright}${colors.green}🎉 Release successfully finished!${colors.reset}\n`,
+    );
+  } else {
+    console.log(
+      `\n${colors.bright}${colors.yellow}⚠️  DRY RUN COMPLETED${colors.reset}`,
+    );
+    console.log(
+      `${colors.yellow}No changes were pushed to Git or NPM.${colors.reset}\n`,
+    );
+  }
+}

package/src/pre-publish.js

@@ -0,0 +1,51 @@
+import { execa } from "execa";
+import fs from "fs/promises";
+import path from "path";
+
+async function readPackageManifest(pkgDir) {
+  const manifestPath = path.join(pkgDir, "package.json");
+  const content = await fs.readFile(manifestPath, "utf-8");
+  return JSON.parse(content);
+}
+
+async function runPackageScript(pkgDir, scriptName) {
+  console.log(`    ⚙️  pnpm run ${scriptName}...`);
+  await execa("pnpm", ["run", scriptName], { cwd: pkgDir });
+}
+
+/**
+ * Execute pre-publish commands (build and/or package) before release
+ * @param {Array} packages - Packages to process
+ * @param {Object} options - CLI options
+ * @param {boolean} options.build - Whether to run build
+ * @param {boolean} options.package - Whether to run package
+ */
+export async function executePrePublishCommands(packages, options) {
+  const requestedScripts = [];
+  if (options.build) requestedScripts.push("build");
+  if (options.package) requestedScripts.push("package");
+
+  if (requestedScripts.length === 0) {
+    return;
+  }
+
+  for (const pkg of packages) {
+    const manifest = await readPackageManifest(pkg.dir);
+    const scripts = manifest.scripts || {};
+    const missingScripts = requestedScripts.filter(
+      (scriptName) => !scripts[scriptName],
+    );
+
+    if (missingScripts.length > 0) {
+      console.log(
+        `    ℹ️  ${manifest.name}: missing script(s): ${missingScripts.join(", ")}. Skipping.`,
+      );
+    }
+
+    for (const scriptName of requestedScripts) {
+      if (scripts[scriptName]) {
+        await runPackageScript(pkg.dir, scriptName);
+      }
+    }
+  }
+}

package/src/publisher.js

@@ -0,0 +1,10 @@
+// author : Lebrun Meddy
+
+import { execa } from 'execa';
+
+export async function publishToRegistry(released, tag, { verbose } = {}) {
+  for (const pkg of released) {
+    if (verbose) console.log(`[verbose] Publishing ${pkg.name} with tag ${tag}`);
+    await execa('pnpm', ['publish', '--filter', pkg.name, '--tag', tag, '--no-git-checks','--access', 'public'], { stdio: 'inherit' });
+  }
+}

package/src/versioner.js

@@ -0,0 +1,23 @@
+// author : Lebrun Meddy
+
+import semver from 'semver';
+import fs from 'fs/promises';
+import path from 'path';
+
+export async function bumpPackages(packages, isPre, preId, { verbose } = {}) {
+  return Promise.all(packages.map(async (pkg) => {
+    if (verbose) console.log(`[verbose] Bumping version for ${pkg.name}`);
+    // Logic: determine bump type (feat=minor, fix=patch, etc.)
+    // For this example, we assume 'patch' or 'prepatch'
+    const type = isPre ? 'prepatch' : 'patch';
+    const next = semver.inc(pkg.currentVersion, type, preId);
+    if (verbose) console.log(`[verbose] New version for ${pkg.name}: ${next}`);
+
+    const pJsonPath = path.join(pkg.dir, 'package.json');
+    const manifest = JSON.parse(await fs.readFile(pJsonPath, 'utf-8'));
+    manifest.version = next;
+    if (verbose) console.log(`[verbose] Writing new version to ${pJsonPath}`);
+    await fs.writeFile(pJsonPath, JSON.stringify(manifest, null, 2) + '\n');
+    return { ...pkg, newVersion: next };
+  }));
+}