npm-workspaces-publish-tool 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 jk89
+
+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,53 @@
+# npm-workspaces-publish-tool
+
+A CLI tool for automating npm package publishing in monorepositories. This tool handles dependency resolution, version validation, build sequencing, and safe publishing with workspace dependency management. Note this is designed for use
+for mono-repos and will not work for projects without npm workspaces.
+
+## Features
+
+- Automatic dependency graph analysis (topological sorting)
+- Smart change detection since last release
+- Version validation and increment checking
+- Git status verification (prevents publishing with uncommitted changes)
+- Workspace dependency management (converts `*` dependencies to exact versions during publish)
+- Dry run mode for testing publish workflow
+- Build sequencing in dependency order
+- Safe rollback of package.json files after publishing
+
+## Installation
+
+```bash
+npm install -g npm-workspaces-publish-tool
+```
+
+## Usage
+
+```bash
+nw-publish [--dry-run]
+```
+
+### Command Options
+
+- `--dry-run`: Runs validation and preview without actual publishing
+
+## Workflow
+1. **Validation Phase**
+   - Builds packages in dependency order
+   - Verifies all modified packages have incremented versions
+   - Ensures git status is clean
+   - Checks for unpushed commits
+
+2. **Publishing Phase**
+   - Replaces workspace `*` dependencies with exact versions
+   - Publishes packages in topological order
+   - Restores original `package.json` files after publishing
+
+## Requirements
+- Node.js 16+
+- Git
+- npm workspaces monorepo structure
+- All packages must have valid `semver` versions
+- Build scripts defined in `package.json` (if needed)
+
+## License
+MIT © Jonathan Kelsey

package/build/package.json

@@ -0,0 +1,28 @@
+{
+    "name": "npm-workspaces-publish-tool",
+    "version": "0.0.1",
+    "description": "An unopinionated tool to assist publishing of npm based mono-repo workspaces",
+    "main": "build/src/cli.js",
+    "type": "module",
+    "bin": {
+        "nw-publish": "build/src/cli.js"
+    },
+    "scripts": {
+        "build": "tsc",
+        "test": "echo \"Error: no test specified\" && exit 1",
+        "relink": "npm unlink nw-publish && npm run build && npm link"
+    },
+    "author": "Jonathan Kelsey",
+    "license": "MIT",
+    "devDependencies": {
+        "@types/node": "^24.0.10",
+        "@types/semver": "^7.7.0",
+        "type-fest": "^4.41.0",
+        "typescript": "^5.8.3"
+    },
+    "dependencies": {
+        "commander": "^14.0.0",
+        "semver": "^7.7.2",
+        "workspace-tools": "^0.38.4"
+    }
+}

package/build/src/bin/cli.js

@@ -0,0 +1,482 @@
+#!/usr/bin/env node
+import { program } from 'commander';
+import { readFileSync, writeFileSync } from 'fs';
+import { createRequire } from 'module';
+import { dirname, join, relative, resolve } from 'path';
+import { cwd as getCwd } from 'process';
+import semver from 'semver';
+import { createDependencyMap, getChangesBetweenRefs, getPackageInfos, getWorkspaces, git, } from 'workspace-tools';
+import { execSync } from 'child_process';
+const require = createRequire(import.meta.url);
+const pkg = require('../../package.json');
+const cwd = getCwd();
+function getLastTag() {
+    const result = git(['tag', '--list', 'v*', '--sort=-v:refname'], { cwd });
+    if (!result.success)
+        return null;
+    const tags = result.stdout.split('\n').filter(Boolean);
+    return tags[0] || null;
+}
+function calculateWorkspaceInDegree(packageInfos, dependencies) {
+    const inDegree = new Map();
+    for (const pkgName of Object.keys(packageInfos)) {
+        inDegree.set(pkgName, 0);
+    }
+    for (const [pkgName, deps] of dependencies) {
+        for (const _ of deps) {
+            inDegree.set(pkgName, (inDegree.get(pkgName) ?? 0) + 1);
+        }
+    }
+    return inDegree;
+}
+function getReleaseOrderFromInDegree(inDegree, dependencies) {
+    const queue = Array.from(inDegree.entries())
+        .filter(([_, count]) => count === 0)
+        .map(([pkg]) => pkg);
+    const order = [];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        order.push(current);
+        for (const [pkg, deps] of dependencies) {
+            if (deps.has(current)) {
+                const newCount = inDegree.get(pkg) - 1;
+                inDegree.set(pkg, newCount);
+                if (newCount === 0) {
+                    queue.push(pkg);
+                }
+            }
+        }
+    }
+    return order;
+}
+function getDirtyMap(workspaces, lastTag) {
+    const dirtyMap = new Map();
+    const changedFiles = lastTag
+        ? getChangesBetweenRefs(lastTag, 'HEAD', [], '', cwd)
+        : [];
+    for (const ws of workspaces) {
+        const isNew = !lastTag;
+        const isDirty = changedFiles.some((f) => f.startsWith(ws.path + '/'));
+        if (isNew) {
+            dirtyMap.set(ws.name, 'new');
+        }
+        else if (isDirty) {
+            dirtyMap.set(ws.name, 'dirty');
+        }
+        else {
+            dirtyMap.set(ws.name, 'unchanged');
+        }
+    }
+    return dirtyMap;
+}
+/**
+ * Returns version changes only for packages marked as 'dirty' in dirtyMap,
+ * comparing current package.json version to the version at the last tag.
+ * Has a `versionIncremented` field indicating if version was increased semver-wise.
+ */
+function getDirtyPackagesVersionChanges(workspaces, dirtyMap, lastTag, cwd) {
+    const result = new Map();
+    if (!lastTag)
+        return result;
+    for (const ws of workspaces) {
+        if (dirtyMap.get(ws.name) !== 'dirty')
+            continue;
+        const pkgPath = resolve(cwd, ws.path, 'package.json');
+        let currentPkg;
+        try {
+            currentPkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        }
+        catch (err) {
+            throw new Error(`Failed to parse current package.json for package "${ws.name}" at path "${pkgPath}": ${err}`);
+        }
+        const newVersion = currentPkg.version;
+        const previousPkgRaw = git(['show', `${lastTag}:${ws.path}/package.json`], { cwd });
+        if (!previousPkgRaw.success) {
+            result.set(ws.name, {
+                oldVersion: null,
+                newVersion,
+                versionChanged: true,
+                versionIncremented: true,
+            });
+            continue;
+        }
+        let previousPkg;
+        try {
+            previousPkg = JSON.parse(previousPkgRaw.stdout);
+        }
+        catch (err) {
+            throw new Error(`Failed to parse package.json from git at tag "${lastTag}" for package "${ws.name}": ${err}`);
+        }
+        const oldVersion = previousPkg.version;
+        const versionChanged = newVersion !== oldVersion;
+        const versionIncremented = oldVersion === null ||
+            (semver.valid(newVersion) && semver.valid(oldVersion))
+            ? semver.gt(newVersion, oldVersion)
+            : false;
+        result.set(ws.name, {
+            oldVersion,
+            newVersion,
+            versionChanged,
+            versionIncremented,
+        });
+    }
+    return result;
+}
+// Check git status to ensure all changes for release are committed appropriately
+function verifyCleanGitStatus(workspaces, dirtyMap, cwd) {
+    // Files changed since last commit
+    const changedFilesRaw = git(['diff', '--name-only', 'HEAD'], { cwd })
+        .stdout.trim()
+        .split('\n')
+        .filter(Boolean);
+    // Files staged for commit
+    const stagedFilesRaw = git(['diff', '--cached', '--name-only'], { cwd })
+        .stdout.trim()
+        .split('\n')
+        .filter(Boolean);
+    // Files unstaged but changed (working dir different from index)
+    const unstagedFilesRaw = git(['diff', '--name-only'], { cwd })
+        .stdout.trim()
+        .split('\n')
+        .filter(Boolean);
+    // Get untracked files from git status
+    const status = git(['status', '--porcelain'], { cwd })
+        .stdout.trim()
+        .split('\n')
+        .filter(Boolean);
+    const untrackedFilesRaw = status
+        .filter((line) => line.startsWith('??'))
+        .map((line) => line.slice(3));
+    // Prepare map of workspace issues
+    const workspaceIssues = new Map();
+    for (const ws of workspaces) {
+        workspaceIssues.set(ws.name, {
+            stagedPackageJsonDirty: false,
+            unstagedPackageJsonDirty: false,
+            stagedFilesNotCommitted: [],
+            unstagedFilesNotStaged: [],
+            untrackedFiles: [],
+        });
+    }
+    function findWorkspaceForFile(filePath) {
+        const absoluteFilePath = resolve(cwd, filePath).replace(/\\/g, '/');
+        for (const ws of workspaces) {
+            const wsPathNormalized = ws.path.replace(/\\/g, '/');
+            if (absoluteFilePath === wsPathNormalized ||
+                absoluteFilePath.startsWith(wsPathNormalized + '/')) {
+                return ws;
+            }
+        }
+        return undefined;
+    }
+    // Helper sets for quick lookup
+    const changedFiles = new Set(changedFilesRaw);
+    const stagedFiles = new Set(stagedFilesRaw);
+    const unstagedFiles = new Set(unstagedFilesRaw);
+    const untrackedFiles = new Set(untrackedFilesRaw);
+    for (const filePath of changedFiles) {
+        const ws = findWorkspaceForFile(filePath);
+        if (!ws)
+            continue;
+        if (dirtyMap.get(ws.name) !== 'new' &&
+            dirtyMap.get(ws.name) !== 'dirty')
+            continue;
+        const issues = workspaceIssues.get(ws.name);
+        const isPackageJson = filePath.endsWith('package.json');
+        const isStaged = stagedFiles.has(filePath);
+        const isUnstaged = unstagedFiles.has(filePath);
+        // FIXME here
+        if (isPackageJson) {
+            if (!isStaged) {
+                issues.unstagedPackageJsonDirty = true;
+            }
+            else {
+                issues.stagedPackageJsonDirty = true;
+            }
+        }
+        else {
+            if (!isStaged) {
+                issues.unstagedFilesNotStaged.push(filePath);
+            }
+            else {
+                issues.stagedFilesNotCommitted.push(filePath);
+            }
+        }
+    }
+    for (const filePath of untrackedFilesRaw) {
+        const ws = findWorkspaceForFile(filePath);
+        if (!ws)
+            continue;
+        if (dirtyMap.get(ws.name) !== 'new' &&
+            dirtyMap.get(ws.name) !== 'dirty')
+            continue;
+        workspaceIssues.get(ws.name).untrackedFiles.push(filePath);
+    }
+    let hasIssues = false;
+    for (const [wsName, issues] of workspaceIssues.entries()) {
+        const { stagedPackageJsonDirty, unstagedPackageJsonDirty, stagedFilesNotCommitted, unstagedFilesNotStaged, untrackedFiles, } = issues;
+        if (!stagedPackageJsonDirty &&
+            !unstagedPackageJsonDirty &&
+            stagedFilesNotCommitted.length === 0 &&
+            unstagedFilesNotStaged.length === 0 &&
+            untrackedFiles.length === 0) {
+            continue;
+        }
+        hasIssues = true;
+        console.error(`❌ Workspace '${wsName}' has issues preventing publish:`);
+        const ws = workspaces.find((w) => w.name === wsName);
+        const missingFiles = [];
+        if (unstagedPackageJsonDirty) {
+            const relativePkgJson = relative(cwd, join(ws.path, 'package.json')).replace(/\\/g, '/');
+            missingFiles.push(relativePkgJson);
+        }
+        for (const file of unstagedFilesNotStaged) {
+            missingFiles.push(file);
+        }
+        if (missingFiles.length > 0) {
+            console.error('  ⚠️ These files have changes since last commit but are NOT staged. Please stage them:');
+            for (const f of missingFiles) {
+                console.error(`    - ${f}`);
+            }
+        }
+        // fix this this is not relative to the workspace root.. FIXME
+        if (stagedPackageJsonDirty) {
+            console.error('  ⚠️ package.json is staged but not committed. Please commit it.');
+        }
+        if (stagedFilesNotCommitted.length > 0) {
+            console.error('  ⚠️ These files are staged but not committed. Please commit them:');
+            for (const f of stagedFilesNotCommitted)
+                console.error(`    - ${f}`);
+        }
+        if (untrackedFiles.length > 0) {
+            console.error('  ⚠️ Untracked files (consider adding or ignoring):');
+            for (const f of untrackedFiles)
+                console.error(`    - ${f}`);
+        }
+    }
+    // Check if root package.json has unstaged changes not committed
+    const rootPackageJsonPath = 'package.json';
+    const isRootPackageJsonChanged = changedFiles.has(rootPackageJsonPath);
+    const isRootPackageJsonStaged = stagedFiles.has(rootPackageJsonPath);
+    const isRootPackageJsonUnstaged = unstagedFiles.has(rootPackageJsonPath);
+    if (isRootPackageJsonChanged) {
+        if (!isRootPackageJsonStaged) {
+            console.error(`❌ Root package.json has unstaged changes. Please stage or discard them before publishing.`);
+            hasIssues = true;
+        }
+        if (isRootPackageJsonStaged) {
+            console.error(`❌ Root package.json is staged but not committed. Please commit it before publishing.`);
+            hasIssues = true;
+        }
+    }
+    if (hasIssues) {
+        console.error('Please commit or stash the above changes before publishing.');
+        return false;
+    }
+    return true;
+}
+function validatePublish() {
+    const lastMonoRepoTag = getLastTag();
+    //console.log('lastMonoRepoTag', lastMonoRepoTag);
+    const workspaces = getWorkspaces(cwd);
+    //console.log('workspaces', workspaces);
+    const packageInfos = getPackageInfos(cwd); // this is a map of package.json "name" field and an unpackaked packagejson with packJsonPath extended into it
+    //const dependencyMap = createDependencyMap(packageInfos);
+    /*console.log(packageInfos);
+    console.log('---------------------------------------');*/
+    const workspacePackageNames = Object.keys(packageInfos); // nodes
+    //console.log('workspacePackageNames', workspacePackageNames);
+    //console.log('---------------------------------------');
+    //console.log(dependencyMap);
+    //const packageGraph = createPackageGraph(packageInfos);
+    //console.log('---------------------------------------');
+    //console.log('packageGraph', packageGraph);
+    const { dependencies, dependents } = createDependencyMap(packageInfos);
+    const roots = workspacePackageNames.filter((name) => !dependencies.get(name)?.size);
+    const visited = new Set();
+    function buildNode(name) {
+        if (visited.has(name)) {
+            return { name, children: [] };
+        }
+        visited.add(name);
+        const kids = Array.from(dependents.get(name) ?? []);
+        return { name, children: kids.map(buildNode) };
+    }
+    const tree = roots.map(buildNode);
+    console.log('tree', JSON.stringify(tree, null, 4));
+    const inDegree = calculateWorkspaceInDegree(packageInfos, dependencies);
+    console.log('inDegree', inDegree);
+    // Determine release order
+    const releaseOrder = getReleaseOrderFromInDegree(inDegree, dependencies);
+    console.log('releaseOrder', releaseOrder);
+    // Determine status of each workspace
+    const dirtyMap = getDirtyMap(workspaces, lastMonoRepoTag);
+    console.log('dirtyMap', dirtyMap);
+    // Determine which dirty packages have had their version field updated (which permits them to be published) if we have dirty packages which have not all been incremented
+    // Determine which dirty packages have version changes
+    const dirtyVersionChanges = getDirtyPackagesVersionChanges(workspaces, dirtyMap, lastMonoRepoTag, cwd);
+    let hasError = false;
+    for (const [pkgName, { oldVersion, newVersion, versionChanged, versionIncremented },] of dirtyVersionChanges.entries()) {
+        if (!semver.valid(newVersion)) {
+            console.error(`❌ Package "${pkgName}" has an invalid current version: "${newVersion}".`);
+            hasError = true;
+            continue;
+        }
+        if (!versionChanged) {
+            console.error(`❌ Package "${pkgName}" was modified but the version has not been updated (still "${newVersion}").`);
+            hasError = true;
+            // Print changed files directly from git using path as pattern
+            const ws = workspaces.find((w) => w.name === pkgName);
+            try {
+                const changedFiles = getChangesBetweenRefs(lastMonoRepoTag, 'HEAD', [], ws.path, // use path as pattern for precision
+                cwd);
+                if (changedFiles.length > 0) {
+                    console.error(`   ↪ Changed files in "${pkgName}":`);
+                    for (const file of changedFiles) {
+                        console.error(`     - ${file.replace(ws.path + '/', '')}`);
+                    }
+                }
+            }
+            catch (err) {
+                console.error(`   ⚠️ Failed to get changed files for "${pkgName}": ${err}`);
+            }
+            continue;
+        }
+        if (!versionIncremented) {
+            console.error(`❌ Package "${pkgName}" version changed from "${oldVersion}" to "${newVersion}", but the new version is not greater (semver).`);
+            hasError = true;
+            continue;
+        }
+        console.log(`✅ Package "${pkgName}" is ready to publish. Version increased from "${oldVersion}" to "${newVersion}".`);
+    }
+    if (hasError) {
+        console.error('\nFix the above issues before publishing.\n');
+        process.exit(1);
+    }
+    // Now if we get this far we have a possible combination of 'unchanged', 'dirty' but incremented correctly, or new.
+    // Before we set of ensure that we have commited all of our changes. And that our git status is clean.
+    const cleanGitStatus = verifyCleanGitStatus(workspaces, dirtyMap, cwd);
+    if (!cleanGitStatus)
+        process.exit(1);
+    // Print publish summary
+    console.log('\nPublish summary:\n');
+    const packagesToRelease = [];
+    for (const pkgName of releaseOrder) {
+        const status = dirtyMap.get(pkgName);
+        const versionInfo = dirtyVersionChanges.get(pkgName);
+        if (status === 'new') {
+            packagesToRelease.push(pkgName);
+            const ws = workspaces.find((w) => w.name === pkgName);
+            const currentVersion = JSON.parse(readFileSync(resolve(cwd, ws.path, 'package.json'), 'utf8')).version;
+            console.log(`🆕 ${pkgName} @ ${currentVersion} (new)`);
+        }
+        if (status === 'dirty' && versionInfo?.versionIncremented) {
+            packagesToRelease.push(pkgName);
+            console.log(`⬆️ ${pkgName}: ${versionInfo.oldVersion} → ${versionInfo.newVersion} (version incremented)`);
+        }
+        if (status === 'unchanged') {
+            const ws = workspaces.find((w) => w.name === pkgName);
+            const currentVersion = JSON.parse(readFileSync(resolve(cwd, ws.path, 'package.json'), 'utf8')).version;
+            console.log(`✔️ ${pkgName} @ ${currentVersion} (unchanged)`);
+        }
+    }
+    console.log('');
+    // Now return useful information to the main program
+    return { releaseOrder, packageInfos };
+}
+export function replaceWorkspaceDepsWithVersions(packageInfos) {
+    for (const pkgName in packageInfos) {
+        const pkgInfo = packageInfos[pkgName];
+        let changed = false;
+        [
+            'dependencies',
+            'devDependencies',
+            'peerDependencies',
+            'optionalDependencies',
+        ].forEach((depType) => {
+            const deps = pkgInfo.packageJson[depType];
+            if (!deps)
+                return;
+            for (const depName in deps) {
+                if (deps[depName] === '*') {
+                    const wsPkg = packageInfos[depName];
+                    if (wsPkg) {
+                        deps[depName] = wsPkg.packageJson.version;
+                        changed = true;
+                    }
+                }
+            }
+        });
+        if (changed) {
+            writeFileSync(pkgInfo.packageJsonPath, JSON.stringify(pkgInfo.packageJson, null, 2));
+        }
+    }
+}
+export function restoreWorkspaceDepsToStar(packageInfos) {
+    for (const pkgName in packageInfos) {
+        const pkgInfo = packageInfos[pkgName];
+        let changed = false;
+        [
+            'dependencies',
+            'devDependencies',
+            'peerDependencies',
+            'optionalDependencies',
+        ].forEach((depType) => {
+            const deps = pkgInfo.packageJson[depType];
+            if (!deps)
+                return;
+            for (const depName in deps) {
+                if (typeof deps[depName] === 'string' &&
+                    deps[depName] !== '*' &&
+                    packageInfos[depName]) {
+                    deps[depName] = '*';
+                    changed = true;
+                }
+            }
+        });
+        if (changed) {
+            writeFileSync(pkgInfo.packageJsonPath, JSON.stringify(pkgInfo.packageJson, null, 2));
+        }
+    }
+}
+export function runNpmPublishInReleaseOrder(releaseOrder, packageInfos) {
+    for (const packageName of releaseOrder) {
+        const pkgInfo = packageInfos[packageName];
+        const pkgDir = dirname(pkgInfo.packageJsonPath);
+        execSync('npm publish', { cwd: pkgDir, stdio: 'inherit' });
+    }
+}
+program.name(pkg.name).description(pkg.description).version(pkg.version);
+program
+    .command('publish')
+    .description('Publish packages')
+    .option('--dry-run', 'Run the publish command without making changes')
+    .action((options) => {
+    const { packageInfos, releaseOrder } = validatePublish();
+    if (options.dryRun) {
+        console.log('Dry run: no publishing will be performed.');
+    }
+    else {
+        try {
+            console.log('Replacing workspace dependencies "*" with actual versions...');
+            replaceWorkspaceDepsWithVersions(packageInfos);
+            console.log('Publishing packages in release order...');
+            runNpmPublishInReleaseOrder(releaseOrder, packageInfos);
+            console.log('Publish process completed.');
+        }
+        catch (error) {
+            console.error('Publishing failed:', error);
+        }
+        finally {
+            console.log('Restoring workspace dependencies back to "*" ...');
+            try {
+                restoreWorkspaceDepsToStar(packageInfos);
+                console.log('Restoration complete.');
+            }
+            catch (restoreError) {
+                console.error('Failed to restore workspace dependencies:', restoreError);
+            }
+        }
+    }
+});
+program.parse(process.argv);