@bobfrankston/npmglobalize 1.0.198 → 1.0.200

package/README.md

@@ -157,6 +157,51 @@ npmglobalize --fix        # Runs npm audit fix
 npmglobalize --no-fix
 ```
 
+### 🧩 Install Scripts (npm `allowScripts`)
+
+npm 11.17+ skips install-time lifecycle scripts (`preinstall`/`install`/
+`postinstall`) for packages that aren't on an allowlist. A **global** install
+has no project `package.json` to record approvals in, so without help a
+postinstall you wrote yourself silently never runs while the install still
+exits 0 — e.g. `@bobfrankston/msger`'s postinstall copies its native binary
+into the per-user bin dir its launcher reads from, and skipping it leaves a
+stale exe behind a green checkmark.
+
+npmglobalize therefore allowlists **your own packages** on the global install
+it performs — it just built and published them from your source, so they're
+trusted — and leaves third-party packages gated:
+
+```
+> npm install -g @bobfrankston/winpos@2.0.51 --allow-scripts @bobfrankston/winpos,@bobfrankston/msger,@bobfrankston/msgcommon
+```
+
+Anything npm skips is reported rather than buried in the captured output:
+
+```
+  · Skipped koffi@2.16.3 install script — prebuilt-binary fetcher, the package ships binaries; normally harmless.
+  ⚠ npm skipped install scripts for third-party packages: sharp@0.33.0
+      sharp@0.33.0 (install: node install/check)
+    These may be broken at runtime — no prebuilt fallback recognized.
+    To run them anyway: npm install -g @bobfrankston/winpos@2.0.51 --allow-scripts @bobfrankston/winpos,@bobfrankston/msger,koffi,sharp
+```
+
+Two details worth knowing:
+
+- **Prebuilt fetchers are called out separately.** npm names the skipped
+  script, so a runner like `cnoke`, `prebuild-install`, `node-gyp-build`,
+  `prebuildify` or `napi-postinstall` is recognized as one that only compiles
+  when no prebuild matches. Those packages ship working binaries — koffi
+  carries `build/koffi/<platform>/koffi.node` for every platform it supports —
+  so the skip gets an informational note, not a warning.
+- **The suggested re-run command includes your own packages.** npm takes the
+  allowlist from the first source that has one rather than merging sources, so
+  a command naming only the third-party package would silently re-gate yours.
+  Always run the full list.
+
+An own-scope package showing up as skipped is reported louder — that means the
+allowlist missed it, usually a transitive dep not present in the local
+`node_modules` tree.
+
 ### 🔑 OAuth Credentials Handling
 
 `npmglobalize` automatically detects `credentials.json` files and handles them based on OAuth app type:
@@ -534,8 +579,9 @@ is planned.
 
 ### `upstream` — who consumes this package
 
-Bookkeeping, not a setting. When a package with `file:` deps publishes,
-npmglobalize appends an entry to each **dependency's** `.globalize.json5`:
+**Experimental.** Bookkeeping, not a setting. When a package with `file:` deps
+publishes, npmglobalize appends an entry to each **dependency's**
+`.globalize.json5`:
 
 ```json5
 {
@@ -557,19 +603,42 @@ checkout path, its version at the time, and the date.
 
 Only **immediate** consumers are recorded. A full consumer tree is a walk, not
 a copy: follow each entry's path and read that package's own `upstream` list.
-
-The list is **FYI for now** — it is recorded, preserved across publishes, and
-printed in the Release Summary of the package that owns it. Nothing is
-rebuilt, republished, or reinstalled on its behalf. An entry is added the
-first time a consumer publishes after this feature landed, and refreshed in
-place on every publish after that.
-
-The entry is written into the dependency's own checkout, then committed there
-(`Record upstream <consumer>@<version>`) and pushed if that repo has a remote.
-Only `.globalize.json5` is staged and committed, by pathspec — anything else
-the dependency had staged or modified is left exactly as it was. If the
-dependency isn't a git repo, or ignores `.globalize.json5`, the file is still
-written and the commit is skipped.
+That keeps each file small and self-maintaining — no package has to know about
+anything beyond its own direct consumers.
+
+The list is **FYI** — it is recorded, preserved across publishes, and printed
+in the Release Summary of the package that owns it. Nothing is rebuilt,
+republished, or reinstalled on its behalf. An entry appears the first time a
+consumer publishes, and is refreshed in place on every publish after that.
+
+#### Scope and limits
+
+**`file:` deps only.** A dependency referenced by npm version (`"^0.1.39"`)
+is never recorded, because npmglobalize has no checkout path for it — it
+consumes the published tarball, not a sibling directory. To have a consumer
+show up in a library's list, that consumer must reference it as
+`file:../<lib>`.
+
+**Usually not committed.** The entry is written into the dependency's own
+checkout, and npmglobalize then tries to commit it there
+(`Record upstream <consumer>@<version>`) and push if that repo has a remote.
+In practice that commit is usually skipped: `.globalize.json5` is in the
+standard ignore template, so most repos ignore it and the entry stays as
+untracked local state. That is a reasonable failure mode for an experimental
+mechanism — the list rewrites itself on every publish, so there is nothing to
+merge and nothing to reconcile between machines. It also means the list is
+**per-machine**, not shared history.
+
+When the commit does happen (a repo that tracks its `.globalize.json5`, as
+npmglobalize itself does), only that one file is staged and committed by
+pathspec — anything else the dependency had staged or modified is left exactly
+as it was. A dependency that isn't a git repo is written and skipped the same
+way.
+
+The alternative would be recording this in `package.json`, which is tracked
+and published — every consumer of a library would then download that library's
+list of local checkout paths in its tarball. Keeping it in `.globalize.json5`
+keeps it out of the package entirely.
 
 ## Common Workflows
 

package/lib.js

@@ -3514,28 +3514,58 @@ function allowOwnScriptsArgs(dir) {
     const own = ownScopePackages(dir);
     return own.length ? ['--allow-scripts', own.join(',')] : [];
 }
+/** Install-script runners that fetch or select a prebuilt binary and only
+ *  compile when no prebuild matches the platform. A package using one of these
+ *  ships working binaries in its tarball, so a skipped script is very rarely
+ *  the thing that breaks it — koffi (cnoke) is the standing example: it carries
+ *  build/koffi/<platform>/koffi.node for every platform it supports. */
+const PREBUILT_SCRIPT_RUNNERS = /\b(prebuild-install|node-gyp-build|prebuildify|cnoke|napi-postinstall)\b/;
 /** A skipped postinstall can leave a package broken at runtime (puppeteer
  *  without its browser, native modules unbuilt), so surface the warning
  *  instead of burying it in the captured output. Own-scope packages are
  *  reported separately and louder: those were supposed to be allowed, so
- *  one showing up here means the allowlist missed it. */
-function warnSkippedScripts(combined, allowed = []) {
-    const pkgs = [...combined.matchAll(/^npm warn allow-scripts\s+(\S+@[^\s(]+) \(/gm)];
+ *  one showing up here means the allowlist missed it.
+ *
+ *  npm names the script it skipped in the warn line — "(install: node
+ *  src/cnoke/cnoke.js ... --prebuild)" — so the report can say WHICH script
+ *  and whether it's the kind that has a prebuilt fallback, rather than
+ *  flatly claiming every skip may have broken something. */
+function warnSkippedScripts(combined, allowed = [], pkgSpec) {
+    const pkgs = [...combined.matchAll(/^npm warn allow-scripts\s+(\S+@[^\s(]+) \(([^)]*)\)/gm)]
+        .map(m => ({ spec: m[1], detail: m[2] }));
     if (!pkgs.length)
         return;
     const nameOf = (spec) => spec.replace(/@[^@]+$/, '');
     const first = allowed[0] || '';
     const scope = first.startsWith('@') ? first.slice(0, first.indexOf('/') + 1) : '';
-    const ours = scope ? pkgs.filter(m => nameOf(m[1]).startsWith(scope)) : [];
-    const others = pkgs.filter(m => !ours.includes(m));
+    const ours = scope ? pkgs.filter(p => nameOf(p.spec).startsWith(scope)) : [];
+    const others = pkgs.filter(p => !ours.includes(p));
     if (ours.length) {
-        console.log(colors.red(`  ⚠ Own-scope install scripts still skipped: ${ours.map(m => m[1]).join(', ')}`));
+        console.log(colors.red(`  ⚠ Own-scope install scripts still skipped: ${ours.map(p => p.spec).join(', ')}`));
         console.log(colors.red(`    npmglobalize allowlisted ${allowed.length} own package(s) but missed these — likely transitive deps not present in the local node_modules tree.`));
     }
     if (others.length) {
-        const names = [...new Set(others.map(m => nameOf(m[1])))];
-        console.log(colors.yellow(`  ⚠ npm skipped install scripts for third-party packages: ${others.map(m => m[1]).join(', ')}`));
-        console.log(colors.yellow(`    Package may be broken at runtime. Allow with: npm install -g <pkg> --allow-scripts ${names.join(',')}`));
+        const prebuilt = others.filter(p => PREBUILT_SCRIPT_RUNNERS.test(p.detail));
+        const unknown = others.filter(p => !prebuilt.includes(p));
+        for (const p of prebuilt) {
+            const script = p.detail.split(':')[0];
+            console.log(colors.dim(`  · Skipped ${p.spec} ${script} script — prebuilt-binary fetcher, the package ships binaries; normally harmless.`));
+        }
+        if (unknown.length) {
+            console.log(colors.yellow(`  ⚠ npm skipped install scripts for third-party packages: ${unknown.map(p => p.spec).join(', ')}`));
+            for (const p of unknown)
+                console.log(colors.yellow(`      ${p.spec} (${p.detail})`));
+            console.log(colors.yellow(`    These may be broken at runtime — no prebuilt fallback recognized.`));
+        }
+        // The re-run command must carry the OWN packages too: npm takes the
+        // allowlist from the first source that has one, so a command listing
+        // only the third-party name silently re-gates ours (msger's postinstall
+        // copies its native binary — losing it is the failure this all exists
+        // to prevent). Print the whole list, and the real spec rather than a
+        // <pkg> placeholder nobody can paste.
+        const rerun = [...allowed, ...new Set(others.map(p => nameOf(p.spec)))].join(',');
+        const target = pkgSpec ?? '<pkg>';
+        console.log(colors.dim(`    To run them anyway: npm install -g ${target} --allow-scripts ${rerun}`));
     }
 }
 /** Run npm install -g with retries for registry propagation delay.
@@ -3568,7 +3598,7 @@ async function installGlobalWithRetry(pkgSpec, cwd, isNewPackage = false, maxRet
             const added = combined.match(/^(?:added|changed|removed) \d+ packages?.*$/m);
             if (added)
                 console.log(colors.dim(`  ${added[0]}`));
-            warnSkippedScripts(combined, allowArgs.length ? allowArgs[1].split(',') : []);
+            warnSkippedScripts(combined, allowArgs.length ? allowArgs[1].split(',') : [], pkgSpec);
             // 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.

package/package.json

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