@bobfrankston/npmglobalize 1.0.238 → 1.0.239

package/README.md

@@ -351,6 +351,8 @@ For single-developer projects, this safely pulls remote changes before publishin
 
 **Stale git lock files**: A git that dies mid-write leaves its lock behind (`.git/config.lock`, `.git/index.lock`), and every later git refuses with `could not lock config file …: File exists` or `Unable to create '….lock': File exists`. When a git command fails that way and the lock is more than 10 seconds old, `npmglobalize` deletes the lock, names the file it deleted, and retries the command once. A younger lock may belong to a git that is writing right now, so it is left alone and the failure is reported with the lock's path and age. (2026-09-21)
 
+**Per-directory lock (parallel runs)**: two `npmglobalize` instances can reach the same package within seconds — one run in a package, another in a consumer whose cascade walks into it. Without a guard both bump and publish, and the second one's tag-conflict handler deletes the first one's tag and republishes (dbx10 and upsnarf, 2026-09-24: 1.0.8 then 1.0.9 of each). Every package a run works on is now locked for the duration under `<temp>/npmglobalize-locks/` (outside the package, so the pre-release `git add -A` never commits it). A second instance that meets a live lock **waits** — polling every second, printing `Waiting for npmglobalize PID … to finish with <dir>` every 10 s — and then re-reads the package and continues, which normally means it finds the version already published and does nothing. A lock whose owner PID is no longer running is stale: it is removed, named, and taken. The wait gives up after 15 minutes with the holder's PID, start time, command line and the lock path, so a process that is not an npmglobalize can be spotted and the file deleted by hand. The lock is reentrant within one process, so a diamond in the dependency graph does not deadlock on the shared dependency, and two instances take locks in the same consumer-then-dependency order, so they cannot deadlock on each other. (2026-09-24)
+
 **Note:** This tool is designed for single-developer, single-branch workflows where automatic rebase and tag cleanup are safe operations.
 
 ### 📂 Git Repository Setup

package/lib.d.ts

@@ -860,6 +860,28 @@ export declare function runNpmAuditFix(cwd: string): Promise<void>;
 export declare function runNpmAudit(cwd: string): AuditResult;
 /** Get the version of npmglobalize itself */
 export declare function getToolVersion(): string;
+/** Where the lock for a package directory lives. Exported for the test. */
+export declare function dirLockPath(dir: string): string;
+/** Take the lock for `dir`, waiting for a live holder to finish. Returns the lock path to
+ *  hand back to releaseDirLock. Throws after `maxWaitMs` naming the holder and the lock file. */
+export declare function acquireDirLock(dir: string, opts?: {
+    maxWaitMs?: number;
+}): Promise<string>;
+/** Release a lock taken by acquireDirLock. The file goes only when the outermost holder in
+ *  this process releases, and only if it is still ours. */
+export declare function releaseDirLock(lockPath: string): void;
+/** For the exit handler: drop every lock this process holds, so a ^C leaves nothing behind
+ *  (a leftover would only cost the next run a "stale lock removed" line, but be tidy). */
+export declare function releaseAllDirLocks(): void;
+/**
+ * Publish one package (and, by default, its file: dependencies first). Holds the
+ * per-directory lock for the whole run so a second npmglobalize reaching the same
+ * package waits instead of double-bumping.
+ * @param cwd - the package directory
+ * @param options - CLI options for this run
+ * @param configOptions - values read from the package's .globalize.json5
+ * @returns true when the package was published (or needed nothing), false on failure
+ */
 export declare function globalize(cwd: string, options?: GlobalizeOptions, configOptions?: Partial<GlobalizeOptions>): Promise<boolean>;
 /** Orchestrate globalize across all packages in an npm workspace */
 export declare function globalizeWorkspace(rootDir: string, options?: GlobalizeOptions, configOptions?: Partial<GlobalizeOptions>): Promise<WorkspaceResult>;

package/lib.js

@@ -12,6 +12,7 @@
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
+import { createHash } from 'crypto';
 import { execSync, spawn, spawnSync } from 'child_process';
 import { builtinModules } from 'module';
 import { readConfig as readUserConfig, writeConfig as writeUserConfig, configDir, configPath as userConfigPath } from '@bobfrankston/userconfig';
@@ -826,6 +827,7 @@ export function installCleanupHandlers() {
         return;
     cleanupHandlersInstalled = true;
     process.on('exit', emergencyRestoreDeps);
+    process.on('exit', releaseAllDirLocks); // 2026-09-24 per-directory lock: drop ours on ^C / process.exit
     // Idempotent abort: first ^C prints an immediate ack so the user doesn't
     // press again and accidentally kill the process mid-restore. Subsequent
     // signals while already aborting are absorbed (with a brief reminder).
@@ -7325,7 +7327,185 @@ async function doLocalInstall(cwd, options) {
     }
     return true;
 }
+// ─── Per-directory lock ──────────────────────────────────────────────────────────────────
+// 2026-09-24 15:55 EDT — Claude Code (Fable 5.1), at Bob's direction.
+// Two npmglobalize instances reached the same packages within seconds (a dbx10 run and a
+// setcolor run whose cascade walks into dbx10 and upsnarf): both bumped, both published, and
+// the second one's tag-conflict handler deleted the first one's v1.0.8 tag and republished as
+// v1.0.9. Nothing stopped it because nothing knew another instance was there. Every
+// globalize() call now holds a lock on its package directory for its whole duration. A second
+// instance that meets a live lock WAITS for it (polling, with a status line every 10 s), then
+// re-reads the directory and continues — normally to "already published, nothing to do". A
+// lock whose owner PID is dead is stale and is removed. Reentrant within one process, so a
+// diamond in the dependency graph (A→B→D, A→C→D) does not deadlock on D. Two instances cannot
+// deadlock on each other either: both take locks consumer-first, dependency-second, in the
+// same DAG order.
+//
+// The lock lives OUTSIDE the package directory, under the temp dir, because the pre-release
+// commit does `git add -A` and would commit a file placed in the package.
+const DIR_LOCK_POLL_MS = 1_000;
+const DIR_LOCK_STATUS_EVERY_MS = 10_000;
+/** How long to wait on a live lock before giving up. A whole cascade can take minutes on Y:. */
+const DIR_LOCK_MAX_WAIT_MS = 15 * 60_000;
+/** An unreadable lock (half-written or garbage) is given this many polls to become readable
+ *  before it is treated as stale. */
+const DIR_LOCK_UNREADABLE_POLLS = 3;
+/** Locks this process holds: lock file path → reentrancy count. */
+const heldDirLocks = new Map();
+/** Where the lock for a package directory lives. Exported for the test. */
+export function dirLockPath(dir) {
+    // Windows paths compare case-insensitively and npm/junctions mix y:/Y: (see
+    // .llm/arborist-trace.md), so fold case there so both spellings map to one lock.
+    let key = path.resolve(dir);
+    if (process.platform === 'win32')
+        key = key.toLowerCase();
+    const slug = key.replace(/[^a-z0-9]+/gi, '_').slice(-80);
+    const hash = createHash('sha1').update(key).digest('hex').slice(0, 8);
+    return path.join(os.tmpdir(), 'npmglobalize-locks', `${slug}-${hash}.lock`);
+}
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM: the process exists but is not ours to signal — still alive.
+        return error.code === 'EPERM';
+    }
+}
+function readDirLock(lockPath) {
+    try {
+        return JSON.parse(fs.readFileSync(lockPath, 'utf-8'));
+    }
+    catch (error) {
+        // Justified swallow: the lock vanished between our EEXIST and this read (its owner
+        // finished), or it is half-written / garbage. The caller treats null as "unreadable",
+        // re-polls a few times, and then removes the lock as stale — so an unreadable lock
+        // cannot hold anyone forever and nothing is lost by not reporting the parse error.
+        return null;
+    }
+}
+function fmtLockTime(iso) {
+    const time = new Date(iso);
+    return isNaN(time.getTime()) ? iso : time.toLocaleTimeString();
+}
+/** Take the lock for `dir`, waiting for a live holder to finish. Returns the lock path to
+ *  hand back to releaseDirLock. Throws after `maxWaitMs` naming the holder and the lock file. */
+export async function acquireDirLock(dir, opts = {}) {
+    const lockPath = dirLockPath(dir);
+    const held = heldDirLocks.get(lockPath);
+    if (held) { // reentrant: this process already holds it
+        heldDirLocks.set(lockPath, held + 1);
+        return lockPath;
+    }
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    const info = {
+        pid: process.pid,
+        started: new Date().toISOString(),
+        dir: path.resolve(dir),
+        argv: process.argv.slice(1)
+    };
+    const maxWait = opts.maxWaitMs ?? DIR_LOCK_MAX_WAIT_MS;
+    const waitStart = Date.now();
+    let lastStatus = 0;
+    let announced = false;
+    let unreadablePolls = 0;
+    for (;;) {
+        try {
+            fs.writeFileSync(lockPath, JSON.stringify(info, null, 2), { flag: 'wx' }); // atomic create
+            heldDirLocks.set(lockPath, 1);
+            if (announced)
+                console.log(colors.green(`✓ ${info.dir} is free — continuing`));
+            return lockPath;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+        const holder = readDirLock(lockPath);
+        if (!holder) {
+            if (++unreadablePolls >= DIR_LOCK_UNREADABLE_POLLS) {
+                console.log(colors.yellow(`Removing unreadable npmglobalize lock ${lockPath}`));
+                removeLockFile(lockPath);
+                unreadablePolls = 0;
+                continue;
+            }
+        }
+        else if (!isPidAlive(holder.pid)) {
+            console.log(colors.yellow(`Removing stale npmglobalize lock for ${holder.dir}: PID ${holder.pid} (started ${fmtLockTime(holder.started)}) is no longer running`));
+            removeLockFile(lockPath);
+            continue;
+        }
+        else {
+            const waitedMs = Date.now() - waitStart;
+            if (waitedMs > maxWait) {
+                throw new Error(`Gave up after ${Math.round(waitedMs / 60_000)} min waiting for npmglobalize PID ${holder.pid} to finish with ${holder.dir}.\n` +
+                    `  It has held the lock since ${fmtLockTime(holder.started)} running: ${holder.argv.join(' ')}\n` +
+                    `  If PID ${holder.pid} is not an npmglobalize, delete ${lockPath} and rerun.`);
+            }
+            if (Date.now() - lastStatus >= DIR_LOCK_STATUS_EVERY_MS) {
+                lastStatus = Date.now();
+                announced = true;
+                const soFar = waitedMs >= DIR_LOCK_STATUS_EVERY_MS ? ` — ${Math.round(waitedMs / 1000)} s so far` : '';
+                console.log(colors.yellow(`Waiting for npmglobalize PID ${holder.pid} (started ${fmtLockTime(holder.started)}) to finish with ${holder.dir}${soFar}`));
+            }
+        }
+        await new Promise(resolve => setTimeout(resolve, DIR_LOCK_POLL_MS));
+    }
+}
+function removeLockFile(lockPath) {
+    try {
+        fs.unlinkSync(lockPath);
+    }
+    catch (error) {
+        // ENOENT means the owner removed it first — that is the outcome we wanted.
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+}
+/** Release a lock taken by acquireDirLock. The file goes only when the outermost holder in
+ *  this process releases, and only if it is still ours. */
+export function releaseDirLock(lockPath) {
+    const held = heldDirLocks.get(lockPath);
+    if (!held)
+        return;
+    if (held > 1) {
+        heldDirLocks.set(lockPath, held - 1);
+        return;
+    }
+    heldDirLocks.delete(lockPath);
+    const current = readDirLock(lockPath);
+    if (current && current.pid !== process.pid)
+        return; // someone else's now; leave it
+    removeLockFile(lockPath);
+}
+/** For the exit handler: drop every lock this process holds, so a ^C leaves nothing behind
+ *  (a leftover would only cost the next run a "stale lock removed" line, but be tidy). */
+export function releaseAllDirLocks() {
+    for (const lockPath of [...heldDirLocks.keys()]) {
+        heldDirLocks.set(lockPath, 1);
+        releaseDirLock(lockPath);
+    }
+}
+/**
+ * Publish one package (and, by default, its file: dependencies first). Holds the
+ * per-directory lock for the whole run so a second npmglobalize reaching the same
+ * package waits instead of double-bumping.
+ * @param cwd - the package directory
+ * @param options - CLI options for this run
+ * @param configOptions - values read from the package's .globalize.json5
+ * @returns true when the package was published (or needed nothing), false on failure
+ */
 export async function globalize(cwd, options = {}, configOptions = {}) {
+    const lockPath = await acquireDirLock(cwd);
+    try {
+        return await globalizeUnderLock(cwd, options, configOptions);
+    }
+    finally {
+        releaseDirLock(lockPath);
+    }
+}
+async function globalizeUnderLock(cwd, options = {}, configOptions = {}) {
     const { bump = 'patch', noPublish = false, cleanup = false, install = false, link = false, wsl = false, force = false, files = true, dryRun = false, quiet = true, verbose = false, init = false, gitVisibility = 'private', npmVisibility = 'private', message, conform = false, asis = false, updateDeps = false, updateMajor = false, publishDeps = true, // Default to publishing deps for safety
     publishDepsYes = false, // -pd: auto-yes to dep-cascade prompts (private only)
     publicDeps = false, // -public-deps: cascade public visibility to all deps

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/npmglobalize",
-  "version": "1.0.238",
+  "version": "1.0.239",
   "description": "Transform file: dependencies to npm versions for publishing",
   "main": "index.js",
   "type": "module",