@bobfrankston/npmglobalize 1.0.199 → 1.0.201

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/cli.js

@@ -112,6 +112,7 @@ Other Options:
   -force          Continue despite git errors
   -dry-run        Preview what would happen
   -quiet          Suppress npm warnings (default)
+  -noquiet        Show npm warnings (without -verbose's extra detail)
   -verbose        Show detailed output
   -conform        Update .gitignore/.npmignore to best practices
                   (noEmit projects: removes TS ignores from .npmignore)
@@ -268,6 +269,10 @@ function parseArgs(args) {
             case '-quiet':
                 options.quiet = true;
                 break;
+            case '-noquiet':
+                options.quiet = false;
+                options.explicitKeys.add('quiet');
+                break;
             case '-verbose':
                 options.verbose = true;
                 options.quiet = false;

package/lib.js

@@ -5334,9 +5334,9 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
         if (configOptions.link)
             settings.push('--link');
         if (configOptions.npmVisibility)
-            settings.push(`--npm-visibility ${configOptions.npmVisibility}`);
+            settings.push(`-npm ${configOptions.npmVisibility}`);
         if (configOptions.gitVisibility)
-            settings.push(`--git-visibility ${configOptions.gitVisibility}`);
+            settings.push(`-git ${configOptions.gitVisibility}`);
         if (configOptions.conform)
             settings.push('--conform');
         if (configOptions.asis)
@@ -5358,15 +5358,15 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
         if (configOptions.dryRun)
             settings.push('--dry-run');
         if (configOptions.bump)
-            settings.push(`--bump ${configOptions.bump}`);
+            settings.push(`-${configOptions.bump}`);
         if (configOptions.cleanup)
             settings.push('--cleanup');
         if (configOptions.wsl)
             settings.push('--wsl');
         if (configOptions.files === false)
-            settings.push('--no-files');
+            settings.push('-nofiles');
         if (configOptions.quiet === false)
-            settings.push('--no-quiet');
+            settings.push('-noquiet');
         if (configOptions.publishDeps === false)
             settings.push('--no-publish-deps');
         if (configOptions.forcePublish)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/npmglobalize",
-  "version": "1.0.199",
+  "version": "1.0.201",
   "description": "Transform file: dependencies to npm versions for publishing",
   "main": "index.js",
   "type": "module",
@@ -32,7 +32,7 @@
   },
   "dependencies": {
     "@bobfrankston/freezepak": "^0.1.9",
-    "@bobfrankston/importgen": "^0.1.39",
+    "@bobfrankston/importgen": "^0.1.40",
     "@bobfrankston/themecolors": "^0.1.8",
     "@bobfrankston/userconfig": "^1.0.10",
     "@npmcli/package-json": "^7.0.4",
@@ -60,7 +60,7 @@
   ".transformedSnapshot": {
     "dependencies": {
       "@bobfrankston/freezepak": "^0.1.9",
-      "@bobfrankston/importgen": "^0.1.39",
+      "@bobfrankston/importgen": "^0.1.40",
       "@bobfrankston/themecolors": "^0.1.8",
       "@bobfrankston/userconfig": "^1.0.10",
       "@npmcli/package-json": "^7.0.4",

package/lib/config.d.ts

@@ -1,23 +0,0 @@
-import { type NpmCommonConfig } from '@bobfrankston/userconfig';
-import { type GlobalizeOptions } from './types.js';
-/** Read and parse package.json from a directory */
-export declare function readPackageJson(dir: string): any;
-/** Global npm config from %USERPROFILE%\.userconfig\npm.json5 — via @bobfrankston/userconfig */
-export type UserNpmConfig = NpmCommonConfig;
-/** Get the .userconfig directory path (%USERPROFILE%\.userconfig) */
-export declare function getUserConfigDir(): string;
-/** Read global npm config from %USERPROFILE%\.userconfig\npm.json5 */
-export declare function readUserNpmConfig(): UserNpmConfig;
-/** Write global npm config to %USERPROFILE%\.userconfig\npm.json5 */
-export declare function writeUserNpmConfig(config: UserNpmConfig): void;
-/** Read .globalize.json5 config file */
-export declare function readConfig(dir: string): Partial<GlobalizeOptions>;
-/** Write .globalize.json5 config file */
-export declare function writeConfig(dir: string, config: Partial<GlobalizeOptions>, explicitKeys?: Set<string>): void;
-/** Write package.json to a directory */
-export declare function writePackageJson(dir: string, pkg: any): void;
-/** Resolve a file: path to absolute path */
-export declare function resolveFilePath(fileRef: string, baseDir: string): string;
-/** Check if a dependency value is a file: reference */
-export declare function isFileRef(value: string): boolean;
-//# sourceMappingURL=config.d.ts.map

package/lib/config.js

@@ -1,163 +0,0 @@
-import fs from 'fs';
-import path from 'path';
-import JSON5 from 'json5';
-import { readConfig as readUserConfig, writeConfig as writeUserConfig, configDir } from '@bobfrankston/userconfig';
-/** Read and parse package.json from a directory */
-export function readPackageJson(dir) {
-    const pkgPath = path.join(dir, 'package.json');
-    if (!fs.existsSync(pkgPath)) {
-        throw new Error(`package.json not found: ${pkgPath}`);
-    }
-    try {
-        return JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-    }
-    catch (error) {
-        throw new Error(`Failed to parse ${pkgPath}: ${error.message}`);
-    }
-}
-/** Get the .userconfig directory path (%USERPROFILE%\.userconfig) */
-export function getUserConfigDir() {
-    return configDir;
-}
-/** Read global npm config from %USERPROFILE%\.userconfig\npm.json5 */
-export function readUserNpmConfig() {
-    return readUserConfig();
-}
-/** Write global npm config to %USERPROFILE%\.userconfig\npm.json5 */
-export function writeUserNpmConfig(config) {
-    const existing = readUserConfig();
-    const merged = { ...existing, ...config };
-    writeUserConfig(merged);
-}
-/** Read .globalize.json5 config file */
-export function readConfig(dir) {
-    const configPath = path.join(dir, '.globalize.json5');
-    if (!fs.existsSync(configPath)) {
-        return {};
-    }
-    try {
-        const content = fs.readFileSync(configPath, 'utf-8');
-        return JSON5.parse(content);
-    }
-    catch (error) {
-        console.warn(`Warning: Could not parse .globalize.json5 config: ${error.message}`);
-        return {};
-    }
-}
-/** Write .globalize.json5 config file */
-export function writeConfig(dir, config, explicitKeys) {
-    const configPath = path.join(dir, '.globalize.json5');
-    // Define defaults to omit
-    const defaults = {
-        bump: 'patch',
-        files: true,
-        quiet: true,
-        gitVisibility: 'private',
-        npmVisibility: 'private',
-        install: false,
-        wsl: false,
-        force: false,
-        verbose: false,
-        freeze: false,
-        usePaths: true
-    };
-    // Read existing config to preserve values
-    const existing = readConfig(dir);
-    // Filter out temporary flags and default values (unless explicitly set)
-    const filtered = {};
-    const omitKeys = new Set(['cleanup', 'init', 'dryRun', 'message', 'conform', 'asis', 'help', 'error', 'updateDeps', 'updateMajor', 'publishDeps', 'publicDeps', 'forcePublish', 'once', 'cleanNestedModules']);
-    for (const [key, value] of Object.entries(config)) {
-        if (omitKeys.has(key))
-            continue;
-        // Keep if: already in config, explicitly set via CLI, or differs from default
-        const isExplicit = explicitKeys?.has(key);
-        const wasInConfig = key in existing;
-        const differsFromDefault = defaults[key] !== value;
-        if (isExplicit || wasInConfig || differsFromDefault) {
-            filtered[key] = value;
-        }
-    }
-    // Build content with comments
-    const lines = [
-        '{',
-        '  // npmglobalize configuration (JSON5 format - trailing commas OK)',
-        '  // Explicitly set values are preserved here',
-        ''
-    ];
-    // Add configured values
-    const entries = Object.entries(filtered);
-    if (entries.length > 0) {
-        entries.forEach(([key, value]) => {
-            const jsonValue = typeof value === 'string' ? `"${value}"` : JSON.stringify(value);
-            const comma = ','; // JSON5 allows trailing commas
-            // Add inline comment for clarity
-            let comment = '';
-            if (key === 'install')
-                comment = '  // Auto-install globally after publish (from registry)';
-            else if (key === 'link')
-                comment = '  // Install globally via symlink (npm install -g .)';
-            else if (key === 'wsl')
-                comment = '  // Also install in WSL';
-            else if (key === 'files')
-                comment = '  // Keep file: paths after publish';
-            else if (key === 'force')
-                comment = '  // Continue despite git errors';
-            else if (key === 'quiet')
-                comment = '  // Suppress npm warnings';
-            else if (key === 'verbose')
-                comment = '  // Show detailed output';
-            else if (key === 'gitVisibility')
-                comment = '  // private (default) or public';
-            else if (key === 'npmVisibility')
-                comment = '  // private (default) or public';
-            else if (key === 'bump')
-                comment = '  // patch (default), minor, or major';
-            else if (key === 'fix')
-                comment = '  // Auto-run npm audit fix';
-            else if (key === 'local')
-                comment = '  // Local install only (skip transform/publish)';
-            else if (key === 'noPublish')
-                comment = '  // Transform but don\'t publish';
-            else if (key === 'freeze')
-                comment = '  // Freeze node_modules (replace symlinks with real copies)';
-            else if (key === 'usePaths')
-                comment = '  // Resolve file: deps from sibling checkouts (set false for standalone packages)';
-            lines.push(`  "${key}": ${jsonValue}${comma}${comment}`);
-        });
-        lines.push('');
-    }
-    // Add commented reference for all options
-    lines.push('  // Defaults (omitted above):');
-    lines.push('  // "bump": "patch"              // Version bump: patch, minor, major');
-    lines.push('  // "install": false             // Auto-install globally after publish (from registry)');
-    lines.push('  // "link": false               // Install globally via symlink (npm install -g .)');
-    lines.push('  // "wsl": false                 // Also install in WSL');
-    lines.push('  // "files": true                // Keep file: paths after publish');
-    lines.push('  // "force": false               // Continue despite git errors');
-    lines.push('  // "quiet": true                // Suppress npm warnings');
-    lines.push('  // "verbose": false             // Show detailed output');
-    lines.push('  // "gitVisibility": "private"   // Git repo: private or public');
-    lines.push('  // "npmVisibility": "private"   // npm package: private or public');
-    lines.push('  // "fix": false                 // Auto-run npm audit fix');
-    lines.push('  // "local": false              // Local install only (skip transform/publish)');
-    lines.push('  // "noPublish": false          // Transform but don\'t publish');
-    lines.push('  // "freeze": false              // Freeze node_modules (replace symlinks with real copies)');
-    lines.push('  // "usePaths": true              // Resolve file: deps from siblings; false = use latest npm version (standalone)');
-    lines.push('}');
-    fs.writeFileSync(configPath, lines.join('\n') + '\n');
-}
-/** Write package.json to a directory */
-export function writePackageJson(dir, pkg) {
-    const pkgPath = path.join(dir, 'package.json');
-    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
-}
-/** Resolve a file: path to absolute path */
-export function resolveFilePath(fileRef, baseDir) {
-    const relativePath = fileRef.replace(/^file:/, '');
-    return path.resolve(baseDir, relativePath);
-}
-/** Check if a dependency value is a file: reference */
-export function isFileRef(value) {
-    return typeof value === 'string' && value.startsWith('file:');
-}
-//# sourceMappingURL=config.js.map

package/lib/deps.d.ts

@@ -1,42 +0,0 @@
-/**
- * npmglobalize dependency analysis, transformation, and restoration.
- * Handles file: ref discovery, workspace graphs, topological sorting,
- * and transforming file: deps to npm versions for publishing.
- */
-/** Get all file: dependencies from package.json */
-export declare function getFileRefs(pkg: any): Map<string, {
-    key: string;
-    name: string;
-    value: string;
-}>;
-/** Resolve workspace entries to package info. Skips dirs without package.json or with private:true. */
-export declare function resolveWorkspacePackages(rootDir: string): Array<{
-    name: string;
-    dir: string;
-    pkg: any;
-}>;
-/** Build a dependency graph among workspace packages. Returns Map<name, Set<depName>>. */
-export declare function buildDependencyGraph(packages: Array<{
-    name: string;
-    dir: string;
-    pkg: any;
-}>): Map<string, Set<string>>;
-/** Topological sort with cycle detection. Returns package names in dependency order. */
-export declare function topologicalSort(graph: Map<string, Set<string>>): string[];
-/** Transform file: dependencies to npm versions */
-export declare function transformDeps(pkg: any, baseDir: string, verbose?: boolean, forcePublish?: boolean): {
-    transformed: boolean;
-    unpublished: Array<{
-        name: string;
-        version: string;
-        path: string;
-    }>;
-};
-/** Build and print a dependency tree of file: references.
- *  Recursively walks file: deps showing the full hierarchy with indentation. */
-export declare function printDepTree(baseDir: string, indent?: number, visited?: Set<string>): void;
-/** Restore file: dependencies from .dependencies */
-export declare function restoreDeps(pkg: any, verbose?: boolean): boolean;
-/** Check if .dependencies exist (already transformed) */
-export declare function hasBackup(pkg: any): boolean;
-//# sourceMappingURL=deps.d.ts.map