@bobfrankston/npmglobalize 1.0.192 → 1.0.193

package/lib.d.ts

@@ -356,6 +356,38 @@ export declare function ensureWorkspaceDepModules(rootDir: string, members: Arra
     dir: string;
     pkg: any;
 }>, verbose?: boolean): Promise<void>;
+/** Extract the lines a human needs from a failed npm command's output: the
+ *  `npm error` lines minus stack frames and brace-only object-dump fragments,
+ *  deduped. The full output belongs in a log file (saveNpmLog), not the terminal. */
+export declare function distillNpmErrors(combined: string): string[];
+/** Scan a puppeteer browser cache (layout <root>/<browser>/<platform-version>)
+ *  and repair every version folder that has no browser executable in it — the
+ *  residue of a truncated extraction (see extractBrowserArchive for the Node
+ *  26 extract-zip bug that produces these). Per corrupt folder:
+ *  1. If the downloaded archive still sits next to it (the usual case right
+ *     after a truncating run — the hung extraction means puppeteer's cleanup
+ *     never deleted it), finish the extraction with the system unzipper. This
+ *     is the only path that converges on Node 26, where re-extraction by
+ *     puppeteer truncates again every time.
+ *  2. Otherwise delete the folder so the next attempt re-downloads.
+ *
+ *  Timing matters: a truncating install EXITS 0, so the poisoned cache hides
+ *  behind a successful install — and the NEXT install deletes the leftover
+ *  archive before erroring. So this must run right after a SUCCESSFUL install
+ *  (while the archive is still there), not only on failure. */
+export declare function verifyPuppeteerCache(cacheRoot?: string): {
+    repaired: string[];
+    removed: string[];
+};
+/** Detect puppeteer's corrupted-browser-cache failure ("browser folder exists
+ *  but the executable is missing") in failed install output and repair the
+ *  whole cache it points into (verifyPuppeteerCache — the installer checks
+ *  browsers in parallel and only reports the first corrupt one, so siblings
+ *  are usually poisoned too). Returns the folders repaired or removed. */
+export declare function fixPuppeteerCorruptedCache(combined: string): {
+    repaired: string[];
+    removed: string[];
+};
 /** Run a command and return success status */
 export declare function runCommand(cmd: string, args: string[], options?: {
     silent?: boolean;

package/lib.js

@@ -2510,19 +2510,244 @@ export async function ensureWorkspaceDepModules(rootDir, members, verbose = fals
         await suggestPnpmOnInstallFailure(`ensureWorkspaceDepModules: ${root}`);
     }
 }
+/** Extract the lines a human needs from a failed npm command's output: the
+ *  `npm error` lines minus stack frames and brace-only object-dump fragments,
+ *  deduped. The full output belongs in a log file (saveNpmLog), not the terminal. */
+export function distillNpmErrors(combined) {
+    const key = [];
+    const seen = new Set();
+    for (const raw of combined.split('\n')) {
+        const m = raw.trimEnd().match(/^npm (?:error|ERR!)\s?(.*)$/);
+        if (!m || !m[1])
+            continue;
+        const msg = m[1];
+        if (/^\s*at /.test(msg))
+            continue; // stack frames
+        if (/^[\s{}\[\]),]*$/.test(msg))
+            continue; // object-dump punctuation lines
+        if (seen.has(msg))
+            continue;
+        seen.add(msg);
+        key.push(msg);
+    }
+    return key.slice(0, 12);
+}
+/** Write the full output of a failed npm command to a log file under the temp
+ *  dir and return its path (null if the write itself fails). */
+function saveNpmLog(label, content) {
+    try {
+        const dir = path.join(os.tmpdir(), 'npmglobalize-logs');
+        fs.mkdirSync(dir, { recursive: true });
+        const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const file = path.join(dir, `${label.replace(/[^a-z0-9.@-]+/gi, '_')}-${stamp}.log`);
+        fs.writeFileSync(file, content);
+        return file;
+    }
+    catch {
+        return null;
+    }
+}
+/** True if `dir` contains a browser executable somewhere below it. A healthy
+ *  puppeteer browser folder always has one; a truncated extraction doesn't
+ *  (extraction writes the small metadata files first — manifest, ABOUT,
+ *  licenses — so an interrupted one holds only those). */
+function containsBrowserExecutable(dir) {
+    try {
+        for (const entry of fs.readdirSync(dir, { recursive: true })) {
+            const name = String(entry);
+            if (process.platform === 'win32' ? /\.exe$/i.test(name) : /(^|[\\/])(chrome|chrome-headless-shell|firefox)$/.test(name))
+                return true;
+        }
+    }
+    catch {
+        // unreadable — treat as not-a-healthy-browser; caller only acts on puppeteer cache paths
+    }
+    return false;
+}
+/** Extract a puppeteer browser archive with the SYSTEM unzipper into a fresh
+ *  version folder. Workaround for a third-party bug: puppeteer's installer
+ *  unpacks zips with the `extract-zip` package, which on Node 26 silently
+ *  truncates — its promise never resolves, the event loop drains, and the
+ *  process exits 0 after writing only the first few small files. The download
+ *  itself is fine (and the archive is left behind, since the hung promise
+ *  means puppeteer's cleanup never runs), so completing the extraction
+ *  ourselves both repairs the folder and converges where delete-and-retry
+ *  cannot. TODO: drop this when puppeteer/extract-zip fix Node 26 extraction. */
+function extractBrowserArchive(archivePath, folder) {
+    // Git-Bash puts GNU tar (no zip support) first on PATH — use bsdtar
+    // explicitly on Windows; macOS tar is bsdtar; Linux needs unzip.
+    const [cmd, args] = process.platform === 'win32'
+        ? [path.join(process.env.SystemRoot || 'C:\\WINDOWS', 'system32', 'tar.exe'), ['-xf', archivePath, '-C', folder]]
+        : process.platform === 'darwin'
+            ? ['tar', ['-xf', archivePath, '-C', folder]]
+            : ['unzip', ['-oq', archivePath, '-d', folder]];
+    try {
+        fs.rmSync(folder, { recursive: true, force: true });
+        fs.mkdirSync(folder, { recursive: true });
+        const r = spawnSafe(cmd, args, { stdio: 'pipe', encoding: 'utf-8' });
+        return r.status === 0 && containsBrowserExecutable(folder);
+    }
+    catch {
+        return false;
+    }
+}
+/** Scan a puppeteer browser cache (layout <root>/<browser>/<platform-version>)
+ *  and repair every version folder that has no browser executable in it — the
+ *  residue of a truncated extraction (see extractBrowserArchive for the Node
+ *  26 extract-zip bug that produces these). Per corrupt folder:
+ *  1. If the downloaded archive still sits next to it (the usual case right
+ *     after a truncating run — the hung extraction means puppeteer's cleanup
+ *     never deleted it), finish the extraction with the system unzipper. This
+ *     is the only path that converges on Node 26, where re-extraction by
+ *     puppeteer truncates again every time.
+ *  2. Otherwise delete the folder so the next attempt re-downloads.
+ *
+ *  Timing matters: a truncating install EXITS 0, so the poisoned cache hides
+ *  behind a successful install — and the NEXT install deletes the leftover
+ *  archive before erroring. So this must run right after a SUCCESSFUL install
+ *  (while the archive is still there), not only on failure. */
+export function verifyPuppeteerCache(cacheRoot) {
+    const root = cacheRoot || process.env.PUPPETEER_CACHE_DIR || path.join(os.homedir(), '.cache', 'puppeteer');
+    const result = { repaired: [], removed: [] };
+    let browserDirs;
+    try {
+        browserDirs = fs.readdirSync(root, { withFileTypes: true }).filter(d => d.isDirectory());
+    }
+    catch {
+        return result; // no puppeteer cache — nothing to verify
+    }
+    for (const browser of browserDirs) {
+        const browserDir = path.join(root, browser.name);
+        let entries;
+        try {
+            entries = fs.readdirSync(browserDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            // version folders look like win64-148.0.7778.97 / mac_arm-131.0.6778.204
+            if (!entry.isDirectory() || !/^[a-z0-9_]+-[\d.]+$/i.test(entry.name))
+                continue;
+            const folder = path.join(browserDir, entry.name);
+            if (containsBrowserExecutable(folder))
+                continue;
+            try {
+                // archive sits next to the version folder, named e.g.
+                // chrome/148.0.7778.97-chrome-win64.zip for chrome/win64-148.0.7778.97
+                const version = entry.name.slice(entry.name.indexOf('-') + 1);
+                const archive = entries.find(e => e.isFile() && e.name.startsWith(`${version}-`) && e.name.endsWith('.zip'))?.name;
+                if (archive && extractBrowserArchive(path.join(browserDir, archive), folder)) {
+                    fs.rmSync(path.join(browserDir, archive), { force: true }); // puppeteer's own cleanup never ran
+                    result.repaired.push(folder);
+                    continue;
+                }
+                fs.rmSync(folder, { recursive: true, force: true });
+                result.removed.push(folder);
+            }
+            catch {
+                // couldn't repair or delete (locked?) — leave it; install will report it
+            }
+        }
+    }
+    return result;
+}
+/** Detect puppeteer's corrupted-browser-cache failure ("browser folder exists
+ *  but the executable is missing") in failed install output and repair the
+ *  whole cache it points into (verifyPuppeteerCache — the installer checks
+ *  browsers in parallel and only reports the first corrupt one, so siblings
+ *  are usually poisoned too). Returns the folders repaired or removed. */
+export function fixPuppeteerCorruptedCache(combined) {
+    for (const m of combined.matchAll(/The browser folder \((.+?)\) exists but the executable \((.+?)\) is missing/g)) {
+        const folder = m[1];
+        // Only ever touch a puppeteer cache — never an arbitrary path parsed from output
+        if (!/[\\/]puppeteer[\\/]/i.test(folder))
+            continue;
+        // cache layout is <root>/<browser>/<platform-version>
+        return verifyPuppeteerCache(path.dirname(path.dirname(folder)));
+    }
+    return { repaired: [], removed: [] };
+}
+/** npm 11.17+ gates lifecycle scripts behind `allowScripts` — non-covered
+ *  scripts are skipped and the install still exits 0. A skipped postinstall
+ *  can leave the package broken at runtime (puppeteer without its browser,
+ *  native modules unbuilt), so surface the warning instead of burying it in
+ *  the captured output. */
+function warnSkippedScripts(combined) {
+    const pkgs = [...combined.matchAll(/^npm warn allow-scripts\s+(\S+@[^\s(]+) \(/gm)];
+    if (!pkgs.length)
+        return;
+    const names = pkgs.map(m => m[1].replace(/@[^@]+$/, ''));
+    console.log(colors.yellow(`  ⚠ npm skipped install scripts (allowScripts): ${pkgs.map(m => m[1]).join(', ')}`));
+    console.log(colors.yellow(`    Package may be broken at runtime. Allow with: npm config set allow-scripts=${names.join(',')} --location=user`));
+}
 /** Run npm install -g with retries for registry propagation delay.
  *  Brand-new packages (first-time publish) take much longer to become
  *  installable than version bumps, so we use longer waits and more
- *  attempts when `isNewPackage` is true. */
+ *  attempts when `isNewPackage` is true.
+ *
+ *  Output is captured, not streamed: npm failures produce hundreds of lines
+ *  (cleanup warns, stack traces, object dumps). The terminal gets a distilled
+ *  error summary; the full text of all attempts goes to a log file.
+ *  Known-fixable failures (puppeteer's corrupted browser cache) are repaired
+ *  automatically and granted one immediate bonus retry. */
 async function installGlobalWithRetry(pkgSpec, cwd, isNewPackage = false, maxRetries) {
     const retries = maxRetries ?? (isNewPackage ? 6 : 3);
     const delaySec = isNewPackage ? 30 : 10;
-    let result = await runCommandAsync('npm', ['install', '-g', pkgSpec], { cwd, silent: false, showCommand: true });
-    for (let attempt = 1; attempt < retries && !result.success; attempt++) {
+    let fullLog = '';
+    let result = { success: false, output: '', stderr: '' };
+    let attempt = 0;
+    let cacheFixRounds = 0;
+    while (true) {
+        console.log(colors.cyan(`> npm install -g ${pkgSpec}`));
+        result = await runCommandAsync('npm', ['install', '-g', pkgSpec], { cwd, silent: true });
+        const combined = `${result.output}\n${result.stderr}`;
+        fullLog += `===== attempt ${attempt + 1}: npm install -g ${pkgSpec} =====\n${combined}\n`;
+        if (result.success) {
+            const added = combined.match(/^added \d+ packages?.*$/m);
+            if (added)
+                console.log(colors.dim(`  ${added[0]}`));
+            warnSkippedScripts(combined);
+            // A truncated puppeteer browser extraction exits 0, so the install
+            // LOOKS fine while the cache is poisoned for every future install.
+            // Verify now, while the leftover archive still allows a repair.
+            const verify = verifyPuppeteerCache();
+            for (const folder of verify.repaired)
+                console.log(colors.yellow(`  ↻ Repaired truncated puppeteer browser extraction (from cached archive): ${folder}`));
+            for (const folder of verify.removed)
+                console.log(colors.yellow(`  ↻ Removed corrupted puppeteer browser cache (no archive to repair from — will re-download when needed): ${folder}`));
+            return result;
+        }
+        const cleanupFails = (combined.match(/npm warn cleanup\s+\[Error: EPERM/g) || []).length;
+        if (cleanupFails)
+            console.log(colors.dim(`  (npm couldn't remove ${cleanupFails} leftover dir(s) — EPERM cleanup warnings, details in log)`));
+        for (const line of distillNpmErrors(combined))
+            console.error(colors.red(`  ${line}`));
+        // Known-fixable failure: repair and retry immediately — the cause is
+        // local, so waiting for registry propagation is pointless. Puppeteer
+        // reports one corrupted browser per run, so allow a few repair rounds
+        // (each must actually repair or remove a folder to earn another retry).
+        if (cacheFixRounds < 3) {
+            const fix = fixPuppeteerCorruptedCache(combined);
+            if (fix.repaired.length || fix.removed.length) {
+                cacheFixRounds++;
+                for (const folder of fix.repaired)
+                    console.log(colors.yellow(`  ↻ Repaired corrupted puppeteer browser cache (extracted cached archive): ${folder}`));
+                for (const folder of fix.removed)
+                    console.log(colors.yellow(`  ↻ Removed corrupted puppeteer browser cache (will re-download): ${folder}`));
+                console.log(colors.yellow(`    (puppeteer's extract-zip truncates silently on Node 26, leaving folders without executables) — retrying now`));
+                continue;
+            }
+        }
+        attempt++;
+        if (attempt >= retries)
+            break;
         console.log(colors.yellow(`  Retrying install (attempt ${attempt + 1}/${retries}) in ${delaySec} seconds...`));
         sleepSync(delaySec * 1000);
-        result = await runCommandAsync('npm', ['install', '-g', pkgSpec], { cwd, silent: false, showCommand: true });
     }
+    const logFile = saveNpmLog(`install-${pkgSpec === '.' ? path.basename(cwd) : pkgSpec}`, fullLog);
+    if (logFile)
+        console.error(colors.dim(`  Full npm output: ${logFile}`));
     return result;
 }
 /** Run a command and return success status */
@@ -5523,7 +5748,7 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
                 if (pkg.bin && (install || link || wsl)) {
                     if (link) {
                         console.log(`Installing ${pkgName} globally from local directory (link)...`);
-                        const localInstallResult = await runCommandAsync('npm', ['install', '-g', '.'], { cwd, silent: false, showCommand: true });
+                        const localInstallResult = await installGlobalWithRetry('.', cwd, false, 1);
                         if (localInstallResult.success) {
                             console.log(colors.green(`✓ Linked globally: ${pkgName}@${pkgVersion}`));
                         }
@@ -5538,7 +5763,7 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
                         // sibling imports. Local install handles workspace linking correctly.
                         if (pkg.workspaces) {
                             console.log(`Installing ${pkgName}@${pkgVersion} globally from local (workspace)...`);
-                            const localResult = await runCommandAsync('npm', ['install', '-g', '.'], { cwd, silent: false, showCommand: true });
+                            const localResult = await installGlobalWithRetry('.', cwd, false, 1);
                             if (localResult.success) {
                                 console.log(colors.green(`✓ Installed globally: ${pkgName}@${pkgVersion}`));
                             }
@@ -5577,7 +5802,7 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
                             else {
                                 console.log(colors.yellow(`${pkgName}@${pkgVersion} not found on npm — installing from local directory.`));
                                 console.log(colors.dim('  Use -m "message" to publish this version to npm.'));
-                                const localResult = await runCommandAsync('npm', ['install', '-g', '.'], { cwd, silent: false, showCommand: true });
+                                const localResult = await installGlobalWithRetry('.', cwd, false, 1);
                                 if (localResult.success) {
                                     console.log(colors.green(`✓ Installed globally from local: ${pkgName}@${pkgVersion}`));
                                 }
@@ -6361,7 +6586,7 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
         if (link) {
             console.log(`Linking globally: ${pkgName}@${pkgVersion}...`);
             if (!dryRun) {
-                const installResult = await runCommandAsync('npm', ['install', '-g', '.'], { cwd, silent: false, showCommand: true });
+                const installResult = await installGlobalWithRetry('.', cwd, false, 1);
                 if (installResult.success) {
                     globalInstallOk = true;
                     console.log(colors.green(`✓ Linked globally: ${pkgName}@${pkgVersion}`));
@@ -6381,7 +6606,7 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
                 // Workspace packages: install from local for proper workspace linking
                 console.log(`Installing ${pkgName}@${pkgVersion} globally from local (workspace)...`);
                 if (!dryRun) {
-                    const installResult = await runCommandAsync('npm', ['install', '-g', '.'], { cwd, silent: false, showCommand: true });
+                    const installResult = await installGlobalWithRetry('.', cwd, false, 1);
                     if (installResult.success) {
                         globalInstallOk = true;
                         console.log(colors.green(`✓ Installed globally: ${pkgName}@${pkgVersion}`));
@@ -6942,7 +7167,7 @@ export async function globalizeWorkspace(rootDir, options = {}, configOptions =
             // Workspace root is private — always install from local directory
             console.log(`Installing ${pkgName}@${pkgVersion} globally from local directory...`);
             if (!dryRun) {
-                const installResult = await runCommandAsync('npm', ['install', '-g', '.'], { cwd: rootDir, silent: false, showCommand: true });
+                const installResult = await installGlobalWithRetry('.', rootDir, false, 1);
                 if (installResult.success) {
                     console.log(colors.green(`✓ Installed globally: ${pkgName}@${pkgVersion}`));
                 }

package/package.json

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