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

npm install -g @bobfrankston/npmglobalize

Basic Usage

cd your-package
npmglobalize              # Transform + publish (patch version)
npmglobalize --minor      # Bump minor version
npmglobalize --major      # Bump major version

# Or run from anywhere with a path
npmglobalize y:\path\to\your-package

Key Features

🔗 Automatic Dependency Publishing (Default)

By default, npmglobalize ensures all file: dependencies are published before converting them:

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 lxlan)
3. Converts and publishes lxtest

Settings Propagation (Default Behavior): When publishing file: dependencies, these settings are automatically inherited:

• --update-deps / --update-major (update dependencies)
• --fix (run npm audit fix)
• --conform (fix .gitignore/.npmignore/.gitattributes and git config)
• --verbose / --quiet
• --force / --files

⚠️ Visibility Settings (Smart Inheritance):

• --npmVisibility is only inherited by NEW repositories (never published to npm before)
• Existing repositories keep their current npm visibility (public/private) unchanged
• --gitVisibility is inherited by all dependencies

This ensures you can safely set --npmVisibility private as a default for new packages without accidentally changing the visibility of your existing published packages.

Why This Matters: Once a package is published to npm (public or private), changing its visibility later requires careful consideration. This smart inheritance protects your existing packages while making new ones default to safe settings.

Example - safely publish with new packages private by default:

npmglobalize --npmVisibility private
# ✓ Existing npm packages: keep their current visibility
# ✓ New packages (never published): default to private (safe!)
# ✓ Regular npm dependencies (express, etc.): unchanged

Example with configuration file (recommended):

# In main package: create .globalize.json5 with "npmVisibility": "private"
npmglobalize
# ✓ Existing repos: publish with their current npm visibility
# ✓ Brand new repos: inherit private setting

Skip auto-publishing (use with caution):

npmglobalize -npd         # --no-publish-deps

Force republish all file: dependencies even if versions exist:

npmglobalize --force-publish

📦 Dependency Updates

Safe updates (minor/patch only, respects semver):

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):

npmglobalize --update-major

• Updates to latest including major versions
• Shows "(MAJOR)" indicator for breaking changes

Note: The --update-deps flag propagates to all file: dependencies, so one command updates your entire dependency tree.

🔒 Security Auditing

Check vulnerabilities:

npmglobalize              # Shows audit at end

Auto-fix vulnerabilities:

npmglobalize --fix        # Runs npm audit fix

Disable audit:

npmglobalize --no-fix

🔑 OAuth Credentials Handling

npmglobalize automatically detects credentials.json files and handles them based on OAuth app type:

• Desktop/installed apps ("installed" key in JSON): The client_secret is just a public app registration ID, not a real secret. Google's own docs state: "the client_secret is obviously not treated as a secret." These files are kept in the repo — !credentials.json is added to .gitignore/.npmignore to override any broader ignore patterns.

• Web apps ("web" key in JSON): The client_secret is a real secret. These files are automatically added to .gitignore/.npmignore to prevent accidental exposure.

This distinction also drives the push protection auto-bypass: when GitHub blocks a push because it detects an OAuth client secret, npmglobalize checks the credential file type. For installed apps, it auto-bypasses (marking as false_positive) since the credential is public by design.

🔄 File Reference Management

Default behavior (restore file: references after publish):

npmglobalize              # Converts file: → npm, publishes, then restores file:

Keep npm references permanently:

npmglobalize --nofiles    # Don't restore file: references

Just transform without publishing:

npmglobalize -np          # --nopublish (formerly --apply)

Restore from backup:

npmglobalize --cleanup    # Restore original file: references

🔧 Git Integration & Error Recovery

Automatic tag conflict resolution:

npmglobalize --fix-tags   # Auto-fix version/tag mismatches

When a previous publish fails, git tags may conflict with package.json version. The --fix-tags option (or automatic detection) will clean up these conflicts.

Automatic rebase when local is behind remote:

npmglobalize --rebase     # Auto-rebase if behind remote

For single-developer projects, this safely pulls remote changes before publishing.

Failed publish recovery: If a previous run bumped the version locally but the publish or push failed (e.g., network error, push protection), npmglobalize detects this automatically on the next run. It checks whether the current version actually exists on npm — if not, it republishes without re-bumping the version. Unpushed commits from a failed push are also pushed automatically.

GitHub Push Protection (GH013): When GitHub's secret scanning blocks a push, npmglobalize detects the error and checks whether the flagged secrets are actually safe. For Google OAuth desktop/installed app credentials (where the "client_secret" is just a public app identifier, not a real secret), it automatically bypasses push protection via the GitHub API (gh CLI required) and retries the push. For other secret types, it displays the unblock URLs with guidance.

Note: This tool is designed for single-developer, single-branch workflows where automatic rebase and tag cleanup are safe operations.

📂 Git Repository Setup

Change visibility of an existing repo:

npmglobalize -git public     # Makes the GitHub repo public (with confirmation)
npmglobalize -git private    # Makes the GitHub repo private

When initializing a new repository with --init, npmglobalize automatically sets up:

File structure (per programming.md standards):

• .gitignore - Node.js best practices (node_modules, secrets, certificates, etc.)
• .npmignore - Publishing filters (excludes .git, tests, source files, etc.)
  • noEmit projects: *.ts, *.map, and tsconfig.json are kept (not ignored) since TS files are the runtime files
• .gitattributes - Forces LF line endings for all text files

Git configuration (ensures cross-platform compatibility):

git config core.autocrlf false  # Disable CRLF conversion
git config core.eol lf          # Force LF line endings

This ensures consistent line endings across Windows, macOS, and Linux, preventing "modified file" issues caused by line ending differences.

🔍 Understanding "Detached HEAD" Error

What is Detached HEAD? Your git repository is not currently on a branch (like master or main). This happens when you:

• Check out a specific commit: git checkout abc123
• Check out a tag: git checkout v1.0.0
• Have some git operations leave you in this state

Why does it matter? Publishing requires being on a branch so commits and tags can be properly tracked in your repository history.

Common scenarios:

1. Just fixing files with --conform:

   npmglobalize --conform   # ✓ Files get fixed, then exits with helpful message

   The files are already updated! You don't need to run it again.

2. Want to publish (have commits to keep):

   git checkout -B master   # Moves master branch to current commit (merges)
   npmglobalize            # Now works normally

   The -B flag moves your branch pointer to include the detached commits.

3. Want to publish (no commits made, safe to discard):

   git checkout master      # Just switch back to branch
   npmglobalize            # Now works normally

4. Force publish anyway (not recommended):

   npmglobalize --force    # Proceeds despite detached HEAD

   Warning: Commits may be hard to track later.

Command Reference

Release Options

-patch               Bump patch version (default)
-minor               Bump minor version
-major               Bump major version
-nopublish, -np      Just transform, don't publish (persisted to config)
-cleanup             Restore file: dependencies from .dependencies backup
-m, -message <msg>   Custom commit message (forces release even without changes)

Dependency Options

-update-deps, -ud        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 (from registry)
-link           Install globally via symlink (npm install -g .)
-local          Local install only — skip transform/publish, just npm install -g .
-wsl            Also install in WSL
-once           Don't persist flags to .globalize.json5

Mode Options

-files          Keep file: paths after publish (default)
-nofiles        Keep npm versions permanently

Git/npm Visibility

-git private    Set GitHub repo to private (default for new repos)
-git public     Set GitHub repo to public (requires confirmation)
                Works on both new and existing repos
-npm private    Mark npm package private (skip publish) (default)
-npm public     Publish to npm

Workspace Options

-w, -workspace <pkg>   Filter to specific package (repeatable)
-no-workspace          Disable workspace mode at a workspace root
-continue-on-error     Continue if a package fails in workspace mode

Workspace mode is auto-detected when run from a root with "private": true and a workspaces field.

Other Options

-init           Initialize git/npm if needed (creates .gitignore, .npmignore,
                .gitattributes, and configures git for LF line endings)
-force          Continue despite git errors
-dry-run        Preview what would happen
-quiet          Suppress npm warnings (default)
-verbose        Show detailed output
-conform        Update .gitignore/.npmignore/.gitattributes to best practices
                and configure git for LF line endings (fixes existing repos)
                For noEmit projects: removes *.ts/*.map/tsconfig.json from .npmignore
-asis           Skip ignore file checks (or set "asis": true in .globalize.json5)
-fix-tags       Automatically fix version/tag mismatches
-rebase         Automatically rebase if local is behind remote
-show           Show package.json dependency changes
-package, -pkg  Update package.json scripts to use npmglobalize (see below)
-h, -help       Show help
-v, -version    Show version

Using in package.json

You can wire npmglobalize into your package.json scripts so that npm run release handles publishing:

{
  "scripts": {
    "release": "npmglobalize"
  }
}

The --package (-pkg) flag does this automatically — it adds a release script (renaming any existing release/installer scripts to old-release/old-installer):

npmglobalize --package       # Sets up "release": "npmglobalize" in package.json

After that, publishing is just:

npm run release              # Same as running npmglobalize directly
npm run release -- --minor   # Pass flags through

You can also combine it with .globalize.json5 for persistent options so npm run release always uses your preferred settings (install, visibility, etc.).

Configuration File

Settings can be saved in .globalize.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

npmglobalize --install    # Publish + install globally

Release with Dependency Chain

cd my-app                  # Has file: deps
npmglobalize              # Publishes all deps automatically

Safe Dependency Updates

npmglobalize --update-deps  # Update to latest safe versions

Security Fixes

npmglobalize --fix         # Fix vulnerabilities + release

Force Update Everything

npmglobalize --force-publish --update-major

Preview Changes

npmglobalize --dry-run     # See what would happen

How It Works

1. Validates package.json and git status
2. Checks if current version is on npm (recovers from failed publishes)
3. Updates dependencies (if --update-deps)
4. Publishes file: dependencies (if needed)
5. Backs up original file: references to .dependencies
6. Converts file: → npm version references
7. Commits changes
8. Bumps version (using npm version) — skipped if recovering a failed publish
9. Publishes to npm
10. Pushes to git (with push-protection detection and auto-bypass)
11. Installs globally (if --install)
12. Restores file: references (if --files, default)
13. Runs audit (shows security status)

Operational Details

The .dependencies Backup (Internal/Transient)

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.

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.

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 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

Both -flag and --flag are accepted. Single-dash is the primary convention:

npmglobalize -patch      # same as --patch
npmglobalize -np         # same as --nopublish
npmglobalize -local      # same as --local

Persistent vs One-Shot Flags

Some flags are persisted to .globalize.json5 when set from the CLI:

• -install, -link, -wsl, -files, -fix — install/build preferences
• -np (noPublish) — once set, prevents accidental publishes
• -local — remembers "this project is local-only"
• -git/-npm visibility

Other flags are one-shot (never persisted):

• -cleanup, -init, -dry-run, -message — situational actions
• -update-deps, -update-major, -force-publish — explicit per-run choices
• -conform, -asis — one-time fixes

Use -once to prevent any flag from persisting on that run:

npmglobalize -np -once   # No-publish this run only, don't remember it

Local Install (-local)

Skip all transform/publish logic and just run npm install -g . with file: deps as-is. Use this when you want to install a CLI tool locally for your own use without publishing anything:

npmglobalize -local          # Install globally from local directory
npmglobalize -local -wsl     # Also install in WSL

This is useful for:

• Development tools you don't publish
• Testing a CLI before publishing
• Projects with file: deps that should stay as-is

Private Packages

Packages with "private": true in package.json skip the npm publish step. Dependencies are still transformed and restored — the publish is the only thing skipped.

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

# Basic release
npmglobalize

# Run on a different project
npmglobalize y:\dev\myproject

# Auto-fix tag conflicts and rebase
npmglobalize -fix-tags -rebase

# 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 (from registry)
npmglobalize -install -wsl

# Release + link on Windows and WSL (symlink)
npmglobalize -link -wsl

# Install locally without publishing (file: deps stay as-is)
npmglobalize -local

# Restore original file: references
npmglobalize -cleanup

# Initialize new git repo + release
npmglobalize -init

# Migrate package.json scripts to use npmglobalize
npmglobalize -package

# Preview what would happen
npmglobalize -dry-run -verbose

Authentication

Requires npm authentication:

npm login

Check authentication:

npm whoami

Development

Build Check

npmglobalize includes automatic build verification to ensure TypeScript files are compiled before execution. This prevents runtime errors from outdated JavaScript files.

How it works:

• When you run npmglobalize, it automatically checks if .js files are newer than their .ts sources
• If .js files are missing or outdated, execution stops with an error
• The check is skipped if noEmit: true is set in tsconfig.json

Building the project:

npm run build     # Compile TypeScript files
npm run watch     # Watch mode for development
npm run check     # Manually verify build status

Bypassing the check:

npmglobalize --force    # Skip build check (not recommended)

Error example:

❌ Error: TypeScript files not compiled
cli.js is older than cli.ts

Please run: npm run build
Or use --force to skip this check

This ensures you never accidentally run outdated code when the TypeScript source has changed.

License

MIT