@bobfrankston/npmglobalize 1.0.208 → 1.0.209

package/lib.d.ts

@@ -485,6 +485,14 @@ export declare function ensureWorkspaceDepModules(rootDir: string, members: Arra
  *  `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[];
+/** True when a failed install is npm's "no such version" (ETARGET/E404) for the
+ *  very spec we just published — registry propagation or a stale local
+ *  packument, not a broken package. `pkgSpec` is `name@version`. */
+export declare function isPropagationFailure(combined: string, pkgSpec: string): boolean;
+/** What to tell the user when an install fails purely because npm cannot see a
+ *  just-published version yet. Says what IS true (published, will install),
+ *  what is NOT (nothing wrong with the package), and one command that works. */
+export declare function propagationHelp(pkgSpec: 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

package/lib.js

@@ -2128,13 +2128,30 @@ async function npmInstallWithCleanRetry(dir, verbose, context) {
  *  resolvable. We wait longer and re-probe `npm view` for the version
  *  string until it shows up (or we hit the cap). */
 function waitForNpmVersion(pkgName, version, isNewPackage = false, maxWaitMs) {
-    const effectiveMaxWait = maxWaitMs ?? (isNewPackage ? 600000 : 180000);
-    const interval = isNewPackage ? 5000 : 3000;
+    // 2026-09-01 10:15 EDT — Claude Code (Opus 5), at Bob's direction.
+    // This loop was polling npm's LOCAL cache, not the registry. Registry
+    // packuments carry `cache-control: public, max-age=300`, and npm's default
+    // (prefer-online=false) serves a cached packument for that whole window
+    // without revalidating — so once the first probe cached a packument that
+    // predates the publish, every probe for the next 5 minutes returned the
+    // same stale answer no matter what the registry actually held. Verified
+    // 2026-09-01 on @bobfrankston/brother-label@1.1.22: the npm debug log for
+    // the failing install shows `http cache … (cache hit)` — it never asked
+    // the registry — while the cached entry's own resHeaders read
+    // `cache-control: public, max-age=300`. `--prefer-online` forces the
+    // staleness check (a conditional request), which is the only way this
+    // poll can observe anything new.
+    // Same run: publish at 13:52:48Z, packument `last-modified 13:57:59Z` —
+    // real propagation took 5m11s, past the old 180s cap for an existing
+    // package. Raised; with a probe that actually revalidates, an early
+    // success still exits immediately, so the higher cap costs nothing.
+    const effectiveMaxWait = maxWaitMs ?? (isNewPackage ? 600000 : 420000);
+    const interval = 5000;
     const maxAttempts = Math.ceil(effectiveMaxWait / interval);
     const suffix = isNewPackage ? ' (new package, may take several minutes)' : '';
     process.stdout.write(`${timestamp()} Waiting for ${pkgName}@${version} on npm registry${suffix}`);
     for (let i = 0; i < maxAttempts; i++) {
-        const result = spawnSafe('npm', ['view', `${pkgName}@${version}`, 'version'], {
+        const result = spawnSafe('npm', ['view', '--prefer-online', `${pkgName}@${version}`, 'version'], {
             shell: process.platform === 'win32',
             stdio: ['pipe', 'pipe', 'pipe'],
             encoding: 'utf-8'
@@ -2147,6 +2164,10 @@ function waitForNpmVersion(pkgName, version, isNewPackage = false, maxWaitMs) {
         sleepSync(interval);
     }
     process.stdout.write(' timed out\n');
+    // Timing out here is not a publish failure — the version is on npm, this
+    // client just cannot see it yet. Say so, or the install error that follows
+    // reads as though the package itself were broken.
+    console.log(colors.yellow(`  ${pkgName}@${version} was published but is still not visible to npm after ${Math.round(effectiveMaxWait / 1000)}s — trying the install anyway.`));
     return false;
 }
 function cleanNestedDepModules(pkg, cwd, verbose) {
@@ -3729,6 +3750,38 @@ export function distillNpmErrors(combined) {
     }
     return key.slice(0, 12);
 }
+// 2026-09-01 10:40 EDT — Claude Code (Opus 5), at Bob's direction: "it installed
+// correctly on a retry - need better error messages". What the run printed was
+// npm's own text — "No matching version found ... In most cases you or one of
+// your dependencies are requesting a package version that doesn't exist" —
+// which is flatly wrong here: WE published that exact version 4 seconds
+// earlier, and a manual retry a minute later installed it. The two helpers
+// below name the real situation instead.
+/** True when a failed install is npm's "no such version" (ETARGET/E404) for the
+ *  very spec we just published — registry propagation or a stale local
+ *  packument, not a broken package. `pkgSpec` is `name@version`. */
+export function isPropagationFailure(combined, pkgSpec) {
+    if (pkgSpec === '.')
+        return false; // local-directory install can't be a registry-visibility problem
+    if (!/npm (?:error|ERR!)\s+code E(?:TARGET|404)\b/.test(combined))
+        return false;
+    const name = pkgSpec.replace(/@[^@/]+$/, ''); // strip the trailing @version, keep any @scope
+    return combined.includes(pkgSpec) || combined.includes(name);
+}
+/** What to tell the user when an install fails purely because npm cannot see a
+ *  just-published version yet. Says what IS true (published, will install),
+ *  what is NOT (nothing wrong with the package), and one command that works. */
+export function propagationHelp(pkgSpec) {
+    return [
+        `${pkgSpec} is published — npm just can't see it from this machine yet.`,
+        `  The registry takes up to several minutes to propagate a new version, and npm`,
+        `  caches the package's version list for 5 minutes (cache-control: max-age=300),`,
+        `  so a retry inside that window can still miss it unless the cache is bypassed.`,
+        `  Nothing is wrong with the package or the publish; the global copy is simply the`,
+        `  previous version until you re-run:`,
+        `      npm install -g --prefer-online ${pkgSpec}`,
+    ];
+}
 /** 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) {
@@ -4054,8 +4107,16 @@ async function installGlobalWithRetry(pkgSpec, cwd, isNewPackage = false, maxRet
     // stays behind npm's allowScripts gate.
     const allowArgs = allowOwnScriptsArgs(cwd);
     while (true) {
-        console.log(colors.cyan(`> npm install -g ${pkgSpec}${allowArgs.length ? ` ${allowArgs.join(' ')}` : ''}`));
-        result = await runCommandAsync('npm', ['install', '-g', pkgSpec, ...allowArgs], { cwd, silent: true });
+        // 2026-09-01 10:15 EDT — Claude Code (Opus 5), at Bob's direction.
+        // `--prefer-online`: this install always targets a version published
+        // seconds ago, so a cached packument is exactly the hazard. Without it
+        // all three ETARGET retries re-read the same stale local cache and are
+        // guaranteed to fail identically — confirmed in npm's debug log for
+        // brother-label@1.1.22 (`http cache … (cache hit)`, no registry
+        // request at all). Costs one conditional request per packument.
+        const online = pkgSpec === '.' ? [] : ['--prefer-online'];
+        console.log(colors.cyan(`> npm install -g ${[...online, pkgSpec, ...allowArgs].join(' ')}`));
+        result = await runCommandAsync('npm', ['install', '-g', ...online, pkgSpec, ...allowArgs], { cwd, silent: true });
         const combined = `${result.output}\n${result.stderr}`;
         fullLog += `===== attempt ${attempt + 1}: npm install -g ${pkgSpec} =====\n${combined}\n`;
         if (result.success) {
@@ -4076,8 +4137,19 @@ async function installGlobalWithRetry(pkgSpec, cwd, isNewPackage = false, maxRet
         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))
+        const propagating = isPropagationFailure(combined, pkgSpec);
+        for (const line of distillNpmErrors(combined)) {
+            // npm's stock follow-up to ETARGET blames the request ("you or one of
+            // your dependencies are requesting a version that doesn't exist").
+            // For a version we published seconds ago that sends the reader
+            // hunting a nonexistent dependency bug — drop it and say the real
+            // thing below.
+            if (propagating && /In most cases you or one of your dependencies/.test(line))
+                continue;
             console.error(colors.red(`  ${line}`));
+        }
+        if (propagating)
+            console.error(colors.yellow(`  ↻ ${pkgSpec} not visible to npm yet — registry propagation, not a bad package.`));
         // 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
@@ -4288,7 +4360,10 @@ async function waitForNpmVersionInWsl(spec, maxWaitMs = 180000) {
     const maxAttempts = Math.ceil(maxWaitMs / interval);
     process.stdout.write(`${timestamp()} Waiting for ${spec} on npm registry (WSL view)`);
     for (let i = 0; i < maxAttempts; i++) {
-        const r = await runCommandAsync('wsl', ['npm', 'view', spec, 'version'], { silent: true });
+        // 2026-09-01 10:15 EDT — Claude Code: --prefer-online for the same
+        // reason as waitForNpmVersion — WSL's npm has its own cache with the
+        // same 300s packument freshness window to poll past.
+        const r = await runCommandAsync('wsl', ['npm', 'view', '--prefer-online', spec, 'version'], { silent: true });
         if (r.success && (r.output || '').trim()) {
             process.stdout.write(' ready\n');
             return true;
@@ -5816,7 +5891,9 @@ async function doLocalInstall(cwd, options) {
             console.log('  [dry-run] Would run: wsl npm install -g .');
         return true;
     }
-    const result = await runCommandAsync('npm', ['install', '-g', '.', ...allowOwnScriptsArgs(cwd)], { cwd, silent: false, showCommand: true });
+    // 2026-09-01 10:55 EDT — Claude Code: see the note on the sibling local-install
+    // path — captured, distilled output instead of raw npm chatter.
+    const result = await installGlobalWithRetry('.', cwd, false, 1);
     if (result.success) {
         console.log(colors.green(`✓ Installed locally: ${pkgName}@${pkgVersion}`));
     }
@@ -5932,7 +6009,16 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
                 console.log('  [dry-run] Would run: wsl npm install -g .');
             return true;
         }
-        const result = await runCommandAsync('npm', ['install', '-g', '.', ...allowOwnScriptsArgs(cwd)], { cwd, silent: false, showCommand: true });
+        // 2026-09-01 10:55 EDT — Claude Code (Opus 5), at Bob's direction. Was a
+        // raw streamed `npm install -g .`, so the terminal got npm's chatter
+        // verbatim — including `npm warn allow-scripts .npmrc allow-scripts
+        // setting is being ignored because --allow-scripts was passed`, a
+        // warning npmglobalize provokes on itself by passing that flag, and
+        // which no reader can act on. installGlobalWithRetry captures the
+        // output and prints only what matters (the added/changed/removed line,
+        // or distilled errors plus a log file), which is what every other
+        // install path here already does.
+        const result = await installGlobalWithRetry('.', cwd, false, 1);
         if (result.success) {
             console.log(colors.green(`✓ Installed locally: ${pkgName}@${pkgVersion}`));
         }
@@ -7243,8 +7329,15 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
                                         console.error(colors.yellow(`  Run 'npm login' to fix, then: npm install -g ${pkgName}@${pkgVersion}`));
                                     }
                                     else {
-                                        console.error(colors.red(`✗ Global install failed`));
-                                        console.error(colors.yellow(`  Try running manually: npm install -g ${pkgName}@${pkgVersion}`));
+                                        const spec = `${pkgName}@${pkgVersion}`;
+                                        if (isPropagationFailure(`${registryInstallResult.output}\n${registryInstallResult.stderr}`, spec)) {
+                                            for (const line of propagationHelp(spec))
+                                                console.error(colors.yellow(`  ${line}`));
+                                        }
+                                        else {
+                                            console.error(colors.red(`✗ Global install failed`));
+                                            console.error(colors.yellow(`  Try running manually: npm install -g --prefer-online ${spec}`));
+                                        }
                                     }
                                 }
                             }
@@ -8088,9 +8181,17 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
                             recordBuildIssue(pkgName, 'warning', `Global install failed (${auth.error || 'auth issue'}) — run 'npm login'`);
                         }
                         else {
-                            console.error(colors.red(`✗ Global install failed`));
-                            console.error(colors.yellow(`  Try running manually: npm install -g ${pkgName}@${pkgVersion}`));
-                            recordBuildIssue(pkgName, 'warning', 'Global install failed');
+                            const spec = `${pkgName}@${pkgVersion}`;
+                            if (isPropagationFailure(`${installResult.output}\n${installResult.stderr}`, spec)) {
+                                for (const line of propagationHelp(spec))
+                                    console.error(colors.yellow(`  ${line}`));
+                                recordBuildIssue(pkgName, 'warning', `Published, but npm could not see ${spec} yet — install with: npm install -g --prefer-online ${spec}`);
+                            }
+                            else {
+                                console.error(colors.red(`✗ Global install failed`));
+                                console.error(colors.yellow(`  Try running manually: npm install -g --prefer-online ${spec}`));
+                                recordBuildIssue(pkgName, 'warning', 'Global install failed');
+                            }
                         }
                     }
                 }

package/package.json

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