@bobfrankston/npmglobalize 1.0.199 → 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/package.json

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