@bobfrankston/npmglobalize 1.0.21 → 1.0.23

package/README.md

@@ -0,0 +1,280 @@
+# npmglobalize
+
+Transform `file:` dependencies to npm versions for publishing.
+
+## Overview
+
+`npmglobalize` automates the workflow of publishing npm packages that use local `file:` references during development. It converts those references to proper npm versions, publishes everything in dependency order, and optionally restores the local references afterward.
+
+## Installation
+
+```bash
+npm install -g @bobfrankston/npmglobalize
+```
+
+## Basic Usage
+
+```bash
+cd your-package
+npmglobalize              # Transform + publish (patch version)
+npmglobalize --minor      # Bump minor version
+npmglobalize --major      # Bump major version
+```
+
+## Key Features
+
+### 🔗 Automatic Dependency Publishing (Default)
+
+By default, `npmglobalize` ensures all `file:` dependencies are published **before** converting them:
+
+```bash
+npmglobalize              # Auto-publishes file: deps in correct order
+```
+
+If you have:
+```
+lxtest
+├── file:../lxlan-node
+│   └── file:../lxland
+└── file:../lxland
+```
+
+It automatically:
+1. Publishes `lxland` (root dependency)
+2. Publishes `lxlan-node` (depends on lxland)
+3. Converts and publishes `lxtest`
+
+**Skip auto-publishing** (use with caution):
+```bash
+npmglobalize -npd         # --no-publish-deps
+```
+
+**Force republish** all file: dependencies even if versions exist:
+```bash
+npmglobalize --force-publish
+```
+
+### 📦 Dependency Updates
+
+**Safe updates** (minor/patch only, respects semver):
+```bash
+npmglobalize --update-deps
+```
+- `express ^4.18.0` → `^4.21.0` ✓
+- `lodash ^4.17.0` → `^4.17.21` ✓  
+- Won't update to `express ^5.0.0` (breaking change)
+
+**Include major updates** (breaking changes):
+```bash
+npmglobalize --update-major
+```
+- Updates to latest including major versions
+- Shows "(MAJOR)" indicator for breaking changes
+
+### 🔒 Security Auditing
+
+**Check vulnerabilities**:
+```bash
+npmglobalize              # Shows audit at end
+```
+
+**Auto-fix vulnerabilities**:
+```bash
+npmglobalize --fix        # Runs npm audit fix
+```
+
+**Disable audit**:
+```bash
+npmglobalize --no-fix
+```
+
+### 🔄 File Reference Management
+
+**Default behavior** (restore file: references after publish):
+```bash
+npmglobalize              # Converts file: → npm, publishes, then restores file:
+```
+
+**Keep npm references** permanently:
+```bash
+npmglobalize --nofiles    # Don't restore file: references
+```
+
+**Just transform** without publishing:
+```bash
+npmglobalize -np          # --nopublish (formerly --apply)
+```
+
+**Restore** from backup:
+```bash
+npmglobalize --cleanup    # Restore original file: references
+```
+
+## Command Reference
+
+### Release Options
+```
+--patch         Bump patch version (default: 1.0.0 → 1.0.1)
+--minor         Bump minor version (1.0.0 → 1.1.0)
+--major         Bump major version (1.0.0 → 2.0.0)
+--nopublish, -np  Just transform, don't publish
+--cleanup       Restore file: dependencies from backup
+```
+
+### Dependency Options
+```
+--update-deps      Update package.json to latest versions (safe: minor/patch)
+--update-major     Allow major version updates (breaking changes)
+--no-publish-deps, -npd  Skip auto-publishing file: dependencies
+--force-publish    Republish dependencies even if version exists
+--fix              Run npm audit fix after transformation
+--no-fix           Don't run npm audit
+```
+
+### Install Options
+```
+--install, -i   Install globally after publish (Windows)
+--wsl           Also install in WSL
+```
+
+### Mode Options
+```
+--files         Keep file: paths after publish (default)
+--nofiles       Keep npm versions permanently
+```
+
+### Git/npm Visibility
+```
+--git private   Make git repo private (default)
+--git public    Make git repo public
+--npm private   Mark package private (skip publish)
+--npm public    Publish to npm (default)
+```
+
+### Other Options
+```
+--init          Initialize git/npm if needed
+--force         Continue despite git errors
+--dry-run       Preview what would happen
+--quiet         Suppress npm warnings (default)
+--verbose       Show detailed output
+--conform       Update .gitignore/.npmignore to best practices
+--asis          Skip ignore file checks
+--help, -h      Show help
+--version, -v   Show version
+```
+
+## Configuration File
+
+Settings can be saved in `.globalize.json5`:
+
+```json5
+{
+  // npmglobalize configuration (JSON5 format)
+  "bump": "patch",           // Version bump type
+  "install": true,           // Auto-install globally
+  "wsl": false,              // Also install in WSL
+  "fix": true,               // Auto-run npm audit fix
+  "verbose": false,          // Show detailed output
+  "gitVisibility": "private",
+  "npmVisibility": "public"
+}
+```
+
+Configuration persists across runs. CLI flags override config file.
+
+## Common Workflows
+
+### Standard Release
+```bash
+npmglobalize --install    # Publish + install globally
+```
+
+### Release with Dependency Chain
+```bash
+cd my-app                  # Has file: deps
+npmglobalize              # Publishes all deps automatically
+```
+
+### Safe Dependency Updates
+```bash
+npmglobalize --update-deps  # Update to latest safe versions
+```
+
+### Security Fixes
+```bash
+npmglobalize --fix         # Fix vulnerabilities + release
+```
+
+### Force Update Everything
+```bash
+npmglobalize --force-publish --update-major
+```
+
+### Preview Changes
+```bash
+npmglobalize --dry-run     # See what would happen
+```
+
+## How It Works
+
+1. **Validates** package.json and git status
+2. **Updates dependencies** (if `--update-deps`)
+3. **Publishes file: dependencies** (if needed)
+4. **Backs up** original file: references to `.dependencies`
+5. **Converts** `file:` → npm version references
+6. **Commits** changes
+7. **Bumps** version (using npm version)
+8. **Publishes** to npm
+9. **Pushes** to git
+10. **Installs** globally (if `--install`)
+11. **Restores** file: references (if `--files`, default)
+12. **Runs audit** (shows security status)
+
+## Version Checking
+
+When publishing file: dependencies, checks if each version exists on npm:
+- ✅ Exists → Skip, use existing version
+- ❌ Missing → Publish it first
+- 🔄 Force → Use `--force-publish` to republish
+
+## Examples
+
+```bash
+# Basic release
+npmglobalize
+
+# Release with updates and security fixes
+npmglobalize --update-deps --fix
+
+# Just update package.json, don't publish
+npmglobalize -np --update-deps
+
+# Force republish all dependencies
+npmglobalize --force-publish --update-major
+
+# Release + install on Windows and WSL
+npmglobalize --install --wsl
+
+# Restore original file: references
+npmglobalize --cleanup
+
+# Preview what would happen
+npmglobalize --dry-run --verbose
+```
+
+## Authentication
+
+Requires npm authentication:
+```bash
+npm login
+```
+
+Check authentication:
+```bash
+npm whoami
+```
+
+## License
+
+MIT

package/lib.js

@@ -1308,6 +1308,28 @@ export async function globalize(cwd, options = {}) {
         }
         catch (error) {
             console.error(colors.red('ERROR: Version bump failed:'), error.message);
+            // Show additional error details if available
+            if (error.stderr || error.stdout || error.code) {
+                if (error.stderr)
+                    console.error('  stderr:', error.stderr);
+                if (error.stdout)
+                    console.error('  stdout:', error.stdout);
+                if (error.code)
+                    console.error('  exit code:', error.code);
+            }
+            // Show the full error stack in verbose mode
+            if (verbose && error.stack) {
+                console.error('  Stack trace:', error.stack);
+            }
+            // Try to provide more context
+            if (error.message?.includes('unknown git error')) {
+                console.error(colors.yellow('\nPossible causes:'));
+                console.error('  • Git hooks (pre-commit, commit-msg) might be failing');
+                console.error('  • GPG signing might be required but not configured');
+                console.error('  • Git config issues (user.name, user.email)');
+                console.error('  • Disk space or permissions issues');
+                console.error(colors.yellow('\nTry running with --verbose or check git status manually'));
+            }
             if (!force) {
                 return false;
             }
@@ -1430,14 +1452,7 @@ export async function globalize(cwd, options = {}) {
             // Install from local directory (faster and works immediately after publish)
             const installResult = runCommand('npm', ['install', '-g', '.'], { cwd, silent: false, shell: true });
             if (installResult.success) {
-                // Verify installation by checking if command exists
-                const verifyResult = runCommand('npm', ['list', '-g', '--depth=0', pkgName], { cwd, silent: true });
-                if (verifyResult.success) {
-                    console.log(colors.green(`✓ Installed and verified globally: ${pkgName}@${pkgVersion}`));
-                }
-                else {
-                    console.log(colors.yellow(`⚠ Install appeared successful but verification failed`));
-                }
+                console.log(colors.green(`✓ Installed globally: ${pkgName}@${pkgVersion}`));
             }
             else {
                 console.error(colors.red(`✗ Global install failed`));
@@ -1454,17 +1469,10 @@ export async function globalize(cwd, options = {}) {
             // Install from local directory in WSL
             const wslResult = runCommand('wsl', ['npm', 'install', '-g', '.'], { cwd, silent: false });
             if (wslResult.success) {
-                // Verify WSL installation
-                const verifyResult = runCommand('wsl', ['npm', 'list', '-g', '--depth=0', pkgName], { cwd, silent: true });
-                if (verifyResult.success) {
-                    console.log(colors.green(`✓ Installed and verified in WSL: ${pkgName}@${pkgVersion}`));
-                }
-                else {
-                    console.log(colors.yellow(`⚠ WSL install appeared successful but verification failed`));
-                }
+                console.log(colors.green(`✓ Installed in WSL: ${pkgName}@${pkgVersion}`));
             }
             else {
-                console.error(colors.yellow('  ✗ WSL install failed (is npm installed in WSL?)'));
+                console.error(colors.yellow('✗ WSL install failed (is npm installed in WSL?)'));
             }
         }
         else {

package/package.json

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