@bobfrankston/npmglobalize 1.0.116 → 1.0.117

package/README.md

@@ -419,22 +419,19 @@ npmglobalize --dry-run     # See what would happen
 
 ## Operational Details
 
-### The `.dependencies` Backup Mechanism
+### The `.dependencies` Backup (Internal/Transient)
 
-When `npmglobalize` transforms `file:` references to npm versions, it stores the originals in a `.dependencies` field (and `.devDependencies`, etc.) inside `package.json`. This is the central safety mechanism — it allows recovery from any failure during the publish cycle.
+**You should never see `.dependencies` in your `package.json` under normal operation.** It is a temporary internal backup that exists only during the brief publish cycle and is removed automatically when the cycle completes.
 
-**How it works:**
-- Before transforming, the original `file:` entries are copied to `.dependencies`
-- After a successful publish, the originals are restored from `.dependencies` and the backup is removed
-- If the process crashes, is interrupted, or exits early (e.g., private package, `--nopublish`), `.dependencies` remains in `package.json`
-- On the **next run**, `transformDeps` detects `.dependencies`, restores the originals first, then re-transforms — so data is never lost
+During publishing, `npmglobalize` temporarily replaces `file:` references with npm version strings. The original `file:` entries are stashed in `.dependencies` (and `.devDependencies`, etc.) so they can be restored afterward. Once the publish succeeds and `file:` paths are restored, `.dependencies` is deleted. A normal run leaves no trace of it.
 
-**Recovery commands:**
-```bash
-npmglobalize -cleanup    # Manually restore file: deps from .dependencies backup
-```
+**If you see `.dependencies` in your `package.json`, something went wrong** — the tool crashed, was killed, or the publish failed partway through. It is not a feature to rely on or edit manually.
+
+**Recovery:**
+- **Re-run `npmglobalize`**: It detects leftover `.dependencies`, restores the originals, and continues normally. Self-healing is automatic.
+- **Manual restore**: `npmglobalize -cleanup` restores file: deps and removes the `.dependencies` backup.
 
-**Why not just restore immediately on error?** The `.dependencies` approach is deliberately persistent. If the tool crashes hard (killed process, power failure, npm timeout), there's no cleanup code to run. The backup in `package.json` survives because it was written before the risky operations began. The next run self-heals.
+**Why a persistent backup?** If the tool crashes hard (killed process, power failure, npm timeout), there's no cleanup code to run. The backup in `package.json` survives because it was written before the risky operations began. The next run self-heals.
 
 ### Flag Conventions
 

package/cli.js

@@ -42,6 +42,8 @@ Install Options:
   -wsl           Also install globally in WSL
   -freeze        Freeze node_modules (replace symlinks with real copies for network shares)
   -nofreeze      Disable freeze
+  -importgen     Run importgen to update import maps before publishing
+  -noimportgen   Disable importgen
   -once          Don't persist flags to .globalize.json5
 
 Mode Options:
@@ -297,6 +299,14 @@ function parseArgs(args) {
             case '-once':
                 options.once = true;
                 break;
+            case '-importgen':
+                options.importgen = true;
+                options.explicitKeys.add('importgen');
+                break;
+            case '-noimportgen':
+                options.importgen = false;
+                options.explicitKeys.add('importgen');
+                break;
             default:
                 if (arg.startsWith('-')) {
                     unrecognized.push(arg);

package/lib.d.ts

@@ -72,6 +72,8 @@ export interface GlobalizeOptions {
     package?: boolean;
     /** Don't persist CLI flags to .globalize.json5 */
     once?: boolean;
+    /** Run importgen to update import maps before publishing */
+    importgen?: boolean;
     /** Local install only — skip transform/publish, just npm install -g . */
     local?: boolean;
     /** Freeze node_modules: replace symlinks/junctions with real copies for network share use */

package/lib.js

@@ -14,6 +14,7 @@ import path from 'path';
 import { execSync, spawnSync } from 'child_process';
 import { readConfig as readUserConfig, writeConfig as writeUserConfig, configDir } from '@bobfrankston/userconfig';
 import { freezeDependencies } from '@bobfrankston/freezepak';
+import { importgen as runImportgen } from '@bobfrankston/importgen';
 /** Wrapper for spawnSync that avoids DEP0190 (args + shell: true).
  *  When shell is true, joins cmd+args into a single command string. */
 function spawnSafe(cmd, args, options = {}) {
@@ -2555,6 +2556,27 @@ export async function globalize(cwd, options = {}, configOptions = {}) {
             console.log('  [dry-run] Would run: npm run build');
         }
     }
+    // Run importgen if enabled (update import maps in HTML files)
+    if (options.importgen) {
+        try {
+            if (!dryRun) {
+                const igResult = runImportgen(cwd);
+                console.log(colors.green('✓ importgen updated import maps'));
+                if (verbose && igResult.depDirs.length > 0) {
+                    console.log(`  ${igResult.depDirs.length} dependency dirs resolved`);
+                }
+            }
+            else {
+                console.log('  [dry-run] Would run: importgen');
+            }
+        }
+        catch (error) {
+            // importgen throws if no HTML file found — that's fine, just skip
+            if (verbose) {
+                console.log(colors.dim(`  importgen skipped: ${error.message}`));
+            }
+        }
+    }
     // Pre-flight check: fix version/tag mismatches silently
     if (!dryRun) {
         fixVersionTagMismatch(cwd, pkg, verbose);
@@ -3844,6 +3866,49 @@ export async function globalizeWorkspace(rootDir, options = {}, configOptions =
     console.log(`Packages (${packages.length}): ${packages.map(p => p.name).join(', ')}`);
     console.log(`Publish order: ${publishOrder.join(' → ')}`);
     console.log('');
+    // Check that workspace packages' deps are hoisted to root (needed for global install)
+    const rootPkg = readPackageJson(rootDir);
+    if (rootPkg.bin) {
+        const wsNames = new Set(packages.map(p => p.name));
+        const rootDeps = { ...rootPkg.dependencies, ...rootPkg.devDependencies };
+        const missing = [];
+        for (const pkgInfo of packages) {
+            const deps = pkgInfo.pkg.dependencies || {};
+            for (const [dep, ver] of Object.entries(deps)) {
+                if (wsNames.has(dep))
+                    continue; // sibling workspace package — bundled
+                if (dep in rootDeps)
+                    continue; // already in root
+                if (missing.some(m => m.dep === dep))
+                    continue; // already flagged
+                missing.push({ dep, version: ver, from: pkgInfo.name });
+            }
+        }
+        if (missing.length > 0) {
+            console.log(colors.yellow('⚠ Workspace packages have dependencies not in root package.json:'));
+            for (const m of missing) {
+                console.log(colors.yellow(`  ${m.dep} (${m.version}) — from ${m.from}`));
+            }
+            console.log(colors.dim('  Global install (npm install -g) only installs root deps.'));
+            if (!options.dryRun) {
+                const hoist = await confirm('Add missing deps to root package.json?', true);
+                if (hoist) {
+                    if (!rootPkg.dependencies)
+                        rootPkg.dependencies = {};
+                    for (const m of missing) {
+                        rootPkg.dependencies[m.dep] = m.version;
+                        console.log(colors.green(`  + ${m.dep}: ${m.version}`));
+                    }
+                    writePackageJson(rootDir, rootPkg);
+                    console.log(colors.green('✓ Hoisted workspace deps to root package.json'));
+                }
+            }
+            else {
+                console.log(colors.dim('  [dry-run] Would offer to hoist missing deps'));
+            }
+            console.log('');
+        }
+    }
     // Handle --cleanup: restore deps for all packages and return
     if (options.cleanup) {
         console.log('Restoring workspace dependencies...');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/npmglobalize",
-  "version": "1.0.116",
+  "version": "1.0.117",
   "description": "Transform file: dependencies to npm versions for publishing",
   "main": "index.js",
   "type": "module",
@@ -32,6 +32,7 @@
   },
   "dependencies": {
     "@bobfrankston/freezepak": "^0.1.4",
+    "@bobfrankston/importgen": "^0.1.31",
     "@bobfrankston/userconfig": "^1.0.4",
     "@npmcli/package-json": "^7.0.4",
     "json5": "^2.2.3",
@@ -45,6 +46,7 @@
   },
   ".dependencies": {
     "@bobfrankston/freezepak": "file:../freezepak",
+    "@bobfrankston/importgen": "file:../importgen",
     "@bobfrankston/userconfig": "file:../userconfig",
     "@npmcli/package-json": "^7.0.4",
     "json5": "^2.2.3",