npm - @bobfrankston/npmglobalize - Versions diffs - 1.0.209 → 1.0.210 - Mend

@bobfrankston/npmglobalize 1.0.209 → 1.0.210

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -1,910 +1,904 @@
-# 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
-# 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:
-```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 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:
-```bash
-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):
-```bash
-# 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):
-```bash
-npmglobalize -npd         # --no-publish-deps
-```
-### 🔍 Prescan (Default)
-Before any transform/publish, `npmglobalize` walks the full `file:` dep graph and reports all problems up front (unresolvable paths, missing `package.json`, unscoped packages with private intent, etc.). This lets you fix the whole punch list at once rather than being interrupted mid-cascade.
-Errors abort (unless `--force`); warnings prompt to continue.
-Skip the prescan with `-no-prescan` / `-nps`.
-#### Workspace skip prescan
-In workspace mode, before processing begins, each package is also checked to decide whether it actually needs work. A package is **skipped** (no rebuild, no version bump, no publish) only if **all** of these are true:
-1. **Working tree clean** — `git status --porcelain .` reports no uncommitted changes for that package's directory.
-2. **Version already on npm** — the version in its `package.json` is published to the registry, and no non-bookkeeping commit (anything outside "Pre-release commit" / "Restore file: dependencies" / "Pre-version cleanup" / "Untrack node_modules") is newer than that version's publish timestamp.
-3. **Build is fresh** — every `.ts` source file (excluding `.d.ts`) has a sibling `.js` whose mtime is ≥ the `.ts` mtime. A missing `.js` or an older `.js` counts as stale.
-4. **No sibling workspace `file:` dep flagged for work** — if another workspace package depends on this one via `file:`, and that dep is being updated in this run, this one is also processed (propagates through the graph in topological order).
-If any condition fails, the package is processed. The prescan prints one line per package with `⟳` for "will process" (and the reason) or `✓` for "skip". Example:
-```
-⟳ mlproc     — uncommitted changes
-⟳ pzip       — stale build (index.ts newer than index.js)
-⟳ stage      — dep pzip is being updated
-✓ puller     — skip (clean, published, build fresh)
-```
-The summary row for a skipped package shows `– name v1.0.0 (skipped — already up to date)`.
-Use `--force` or `--force-publish` to bypass the skip prescan and process every package.
-**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
-**Note:** The `--update-deps` flag propagates to all file: dependencies, so one command updates your entire dependency tree.
-### 🔒 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
-```
-### 🧩 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:
-- **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):
-```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
-```
-### 📝 Release Notes via `.commitmsg`
-For multi-line or reusable release notes, write them to a `.commitmsg` file in the package root instead of passing them on the command line:
-```bash
-cat > .commitmsg <<'EOF'
-Added foo feature
-Fixed bar regression
-EOF
-npmglobalize
-```
-Behavior:
-- If `-m` / `-message` is **not** given and `.commitmsg` exists, its contents are used as the commit message (and force a release even if the working tree is otherwise clean).
-- After a successful `npm publish`, npmglobalize:
-  1. Appends the contents to `npmchanges.md` under a `## v<version> — <YYYY-MM-DD>` header (creating the file if needed)
-  2. Deletes `.commitmsg`
-  3. Commits both changes as `Log v<version> to npmchanges.md` and pushes
-Notes:
-- **Git/GitHub only.** npm publish does not consume git commit messages; `npmchanges.md` lives in the git repo and on GitHub but is excluded from the published npm tarball (the standard `*.md` rule keeps only `README.md`).
-- If both `-m` and `.commitmsg` are present, `-m` wins and `.commitmsg` is left alone (not consumed).
-- If publish fails, `.commitmsg` is preserved for the next attempt.
-- `.commitmsg` is auto-added to `.npmignore` (security pattern) so it never leaks into the tarball.
-### 🔧 Git Integration & Error Recovery
-**Automatic tag conflict resolution**:
-```bash
-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:
-```bash
-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:**
-```bash
-npmglobalize -git public     # Makes the GitHub repo public (with confirmation)
-npmglobalize -git private    # Makes the GitHub repo private
-```
-### Missing local `.git` (adopt vs fresh init)
-When npmglobalize runs in a directory with no `.git`, it first checks for a
-reachable `repository.url` in `package.json`. If found, it offers two paths:
-```
-How would you like to set up git?
-  1) Adopt history from existing remote (recommended)
-  2) Initialize fresh git repository
-  a) Adopt ALL (don't ask again for remaining deps)
-  3) Use local install only (skip git/publish)
-  4) Abort
-```
-**Adopt** runs:
-```bash
-git init
-git remote add origin <package.json repository.url>
-git fetch origin
-# Point HEAD at origin/<defaultBranch> without touching the working tree
-git update-ref refs/heads/<branch> origin/<branch>
-git symbolic-ref HEAD refs/heads/<branch>
-git reset                       # mixed: refresh index, keep working tree
-```
-After adoption, your local files appear as **uncommitted changes on top of the
-remote's HEAD** — `git status` shows the drift, and npmglobalize's normal flow
-will commit them on the next publish. **No force-push is required**, and the
-remote's history is preserved.
-If the remote is not reachable (no `repository` field, network/auth failure,
-deleted repo), the original "Initialize fresh git repository" prompt is shown
-instead.
-CLI flags:
-- `-init` — auto path; adopts if a reachable remote is found, otherwise falls
-  back to fresh `git init` + `gh repo create`.
-- `-adopt` — **strict**: aborts if no reachable remote in `package.json.repository`.
-  Use this when you want to be sure no new GitHub repo is created (e.g. in
-  scripts, or when re-attaching a tree of packages to existing repos).
-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):
-```bash
-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`:**
-   ```bash
-   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):**
-   ```bash
-   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):**
-   ```bash
-   git checkout master      # Just switch back to branch
-   npmglobalize            # Now works normally
-   ```
-4. **Force publish anyway (not recommended):**
-   ```bash
-   npmglobalize --force    # Proceeds despite detached HEAD
-   ```
-   Warning: Commits may be hard to track later.
-## Command Reference
-<!-- NOTE: Keep this in sync with the -help output in cli.ts printHelp().
-     The README expands on options with examples and context;
-     cli.ts is the concise quick-reference. Update both when adding/changing flags.
-     Both -flag and --flag are accepted; single-dash is shown as primary. -->
-### 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)
-                     If -m not given, a `.commitmsg` file (if present) is used instead.
-                     See "Release Notes via .commitmsg" below.
-```
-### Dependency Options
-```
--update-deps, -ud        Update package.json to latest versions (safe: minor/patch)
--update-major            Allow major version updates (breaking changes)
--publish-deps            Auto-publish file: dependencies (default)
--pd                      Like -publish-deps, plus auto-yes to dep-cascade prompts (private only)
--no-publish-deps, -npd   Skip auto-publishing file: dependencies
--no-prescan, -nps        Skip upfront dep-graph prescan
--force-publish           Republish dependencies even if version exists
--fix                     Run npm audit fix after transformation
--no-fix                  Don't run npm audit
--no-use-paths, -nup      Declare package standalone; do not resolve file: deps
-                         from sibling checkouts (see Configuration File)
-```
-### 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 <values>   Comma-separated list of npm options:
-                  private (default) | public — package visibility
-                  ts                         — keep .ts source (and *.map,
-                                               tsconfig.json) in npm tarball
-                  nts                        — exclude .ts source
-                                               (default for non-noEmit projects)
-                Example: -npm public,ts
-```
-`ts` is already the default on git (source is tracked). Pass `-npm ts` to ship
-the same files to npm — useful for debugging installed packages or "source on
-demand" packages. `noEmit` projects automatically ship `.ts` files (they *are*
-the runtime); pass `-npm nts` to override. `allowTs` persists to
-`.globalize.json5`.
-### 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).
-                If package.json.repository.url is reachable, adopts its
-                history instead of creating a fresh repo.
--adopt          Strict adopt: require a reachable git remote in
-                package.json.repository. Abort if probe fails. Skips prompt.
--strict-imports, -import-check
-                Opt in to scanning .ts/.js source for imports of packages not
-                declared in any dependencies bucket. Off by default — the
-                always-declare style this enforces doesn't hold in monorepos
-                that rely on workspace cross-refs or the -public-deps cascade
-                (those produce noisy prompts that get dismissed reflexively,
-                which defeats the safety purpose). Use only on packages where
-                every import is meant to be a direct package.json declaration.
-                When it does fire, it catches silent runtime failures —
-                ERR_MODULE_NOT_FOUND on a clean install of a published tarball
-                that was resolving via an ambient parent/global node_modules
-                at dev time.
--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
--clean-nested-modules, -clean-nested
-                Before npm pack, wipe node_modules/ inside each file: dep
-                target. Fixes arborist "Cannot read properties of null"
-                crashes caused by sibling file: deps with nested
-                node_modules. Suggested automatically when the error hits.
--ts7-report, -deprecation-report
-                Report-only: scan this package and its file: deps for
-                compilerOptions removed in TypeScript 7 and list a migration
-                to-do. Writes nothing.
--tsfix, -ts7-fix
-                One-off utility, NOT part of the main flow: apply the TS7
-                tsconfig migration to a package (and its file: deps) and exit —
-                no build, no commit, no push, no publish. Intended as a
-                temporary tool for fixing a local/subdirectory tsconfig in
-                place. The normal release flow already applies the same
-                migration automatically when a build hits a TS7 deprecation
-                error, so day-to-day you never need this flag.
-                    npmglobalize <path> -tsfix
--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:
-```json
-{
-  "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`):
-```bash
-npmglobalize --package       # Sets up "release": "npmglobalize" in package.json
-```
-After that, publishing is just:
-```bash
-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`:
-```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",
-  "usePaths": true           // Resolve file: deps from sibling checkouts (see below)
-}
-```
-Configuration persists across runs. CLI flags override config file.
-### `usePaths` — Standalone packages
-Default: `true`. Set to `false` (or pass `-no-use-paths` / `-nup`) to mark a
-package as **standalone** — one that should be publishable/installable on a
-machine that does not have sibling `file:` dep checkouts available. Example:
-a backup/recovery utility you want to `npm install -g` on any host.
-Currently this setting is **declarative** — it is parsed, persisted to
-`.globalize.json5`, and surfaced in the settings banner, but the tool does
-not yet change its behavior based on it. Behavior wiring (e.g. resolving
-`file:` deps to the latest published npm version instead of walking siblings)
-is planned.
-### `upstream` — who consumes this package
-**Experimental.** Bookkeeping, not a setting. When a package with `file:` deps
-publishes, npmglobalize appends an entry to each **dependency's**
-`.globalize.json5`:
-```json5
-{
-  "install": true,
-  // FYI: packages that depend on this one (immediate consumers,
-  //      recorded when each of them publishes). Nothing is updated
-  //      automatically; follow each path's own .globalize.json5 to
-  //      walk further out.
-  "upstream": [
-    {"path":"Y:\\dev\\utils\\winpos","version":"2.0.51","updated":"2026-08-09"},
-  ],
-}
-```
-So publishing `winpos` (which has `"@bobfrankston/msger": "file:../msgx/msger"`)
-records winpos in **msger's** config. Each entry carries the consumer's
-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.
-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
-### 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. **Checks** if current version is on npm (recovers from failed publishes)
-3. **Updates dependencies** (if `--update-deps`)
-4. **Builds `file:` deps in topological order**, then the target itself, so consumers' `tsc` reads up-to-date `.d.ts` from sibling checkouts whose source has changed (see [Build Cascade](#build-cascade))
-5. **Publishes file: dependencies** (if needed)
-6. **Backs up** original file: references to `.dependencies`
-7. **Converts** `file:` → npm version references
-8. **Commits** changes
-9. **Bumps** version (using npm version) — skipped if recovering a failed publish
-10. **Publishes** to npm
-11. **Pushes** to git (with push-protection detection and auto-bypass)
-12. **Installs** globally (if `--install`)
-13. **Restores** file: references (if `--files`, default)
-14. **Runs audit** (shows security status)
-## Operational Details
-### Build Cascade
-Before transforming or publishing anything, `npmglobalize` builds `file:` dependencies in topological order — deps before consumers — and then builds the target itself. This guarantees the target's `tsc` reads up-to-date `.d.ts` and `.js` from sibling checkouts even when a dep's source has changed since its last build.
-For each project visited (the target and every transitive `file:` dep):
-- If `tsconfig.json` is missing or has `"noEmit": true` → **skip** (not a TypeScript build), unless the `build` script runs `importgen` — a plain-JS browser app still needs its import map regenerated.
-- If `tsconfig.json` exists but `package.json` has no `"build"` script → **prompt** to add `"build": "tsc"` (plus a `tsc -p <dir>` per sub-project — see below). Decline and that project is skipped.
-- Otherwise → run `npm run build`. A failure halts the cascade unless `-force` is passed.
-Cycle-safe via a shared visited set; each project is built at most once per run.
-This complements the existing publish cascade (which ensures version refs are correct) by closing the build-freshness gap that `npm install` alone left open.
-#### Import maps (`importgen`) as a build step
-Browser projects that use [`importgen`](https://www.npmjs.com/package/@bobfrankston/importgen) have historically regenerated their import map from `.vscode/tasks.json`, which only runs when VS Code opens the folder — so a command-line or CI build could publish a stale map. `npmglobalize` treats the import map as a build product and moves the step into the package's own `build` script, where every build path picks it up.
-Before building each project, it checks whether the project is an importgen project, in this order:
-1. `.vscode/tasks.json` has a task whose `command` is `importgen` (the HTML file, if the task names one, is reused).
-2. A root-level `.htm`/`.html` file already contains a `<script type="importmap">` block (`index.html`, `default.html`, `default.htm` are checked first, so a stray `temp.htm` doesn't win).
-3. `importgen` is in `dependencies`/`devDependencies` **and** the project has one of those HTML files — the HTML requirement keeps packages that merely *use* importgen as a library from matching.
-If a signal matches and the `build` script doesn't already run `importgen`, you're prompted to rewrite it — e.g. `"build": "tsc"` → `"build": "importgen default.htm && tsc"`. The HTML file is named explicitly so importgen doesn't have to guess. Decline and `"importgen": false` is written to `.globalize.json5`, which suppresses the prompt for good; `-noimportgen` does the same from the command line.
-Once wired, the freshness check gains a second condition: a project whose build runs importgen is only considered up to date if the generated HTML is at least as new as `package.json`. Adding a dependency changes the import map without touching any `.ts` file, which the source-vs-output comparison alone would miss.
-#### Sub-projects (a second `tsconfig.json` in a sub-directory)
-A package can hold more than one TypeScript project. The common shape is a service worker in `Sw/` with its own `tsconfig.json` (`lib: ["WebWorker"]`, its own `outDir`) that the root `tsconfig.json` lists under `exclude` — so a bare `"build": "tsc"` compiles everything *except* the service worker, and the stale `sw2.js` ships. As with import maps, these have historically been built only by a second `.vscode/tasks.json` watcher, which runs on folder open and nowhere else.
-Before building, `npmglobalize` looks for sub-projects, in this order:
-1. `.vscode/tasks.json` has a task that runs `tsc` with `"options": { "cwd": "${workspaceFolder}/Sw" }` or with `-p`/`--project` naming a sub-directory (authoritative — it's how the project is actually built today; the task's `label` is quoted back in the prompt).
-2. An immediate sub-directory containing its own `tsconfig.json`. Build output and vendored trees (`node_modules`, `prev`, `dist`, `built`, `out`, `wwwroot`, `coverage`, `temp`, `preflight`, dot-directories) are never scanned.
-Nothing is detected when the root `tsconfig.json` uses project `references` — that build graph belongs to `tsc -b` and isn't second-guessed.
-When the `build` script is `tsc`-driven and doesn't already compile a detected sub-project, you're prompted to append it — `"build": "tsc"` → `"build": "tsc && tsc -p Sw"`, or for an importgen project `"build": "importgen default.htm && tsc && tsc -p Sw"`. Already-wired scripts are recognized in any of their spellings (`tsc -p Sw`, `tsc --project ./Sw/tsconfig.json`, `cd Sw && tsc`), and the directory is emitted with its real on-disk casing so the script still works on WSL and CI. Decline and `"subProjects": false` is written to `.globalize.json5`, suppressing the prompt for good; a `"subProjects": ["Sw"]` array pins the list instead of detecting it.
-Sub-projects the build actually compiles are also folded into the freshness check — the package rebuilds when a sub-project's sources are newer than its output. A sub-project that emits *outside* its own directory (`"outDir": ".."`, the usual service-worker case) always reports stale: comparing its sources against the whole package would prove nothing.
-#### TypeScript 6 `types` auto-fix
-TypeScript 6 dropped the legacy behavior of auto-including every installed `@types/*` package. A `tsconfig.json` with no explicit `compilerOptions.types` then loses the Node globals (`process`, `Buffer`, …) and the build fails with `TS2591`.
-Before each build, when the global `tsc` is version 6 or newer, `npmglobalize` patches the project's `tsconfig.json` to add an explicit `types` list — enumerating the installed `@types/*` packages (e.g. `"types": ["node", …]`) — restoring the old behavior. The edit is:
-- **Conservative** — only applied when `compilerOptions.types` is **absent**, `node_modules/@types/node` is actually installed, and there is no `extends` (whose merged `types` can't be seen). An explicit `types` you already set is never overridden.
-- **Format-preserving** — the single `types` key is inserted into the existing `compilerOptions` block; comments, ordering, and indentation are left intact.
-- **Idempotent** — once the list is present, subsequent runs skip it.
-If the patch can't be applied for some reason and the build still fails with `TS2591`, the failure summary prints a hint to add `"types": ["node"]` manually.
-### 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:
-```bash
-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:
-```bash
-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:
-```bash
-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
-```bash
-# 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 git (adopt existing remote if reachable, else fresh) + release
-npmglobalize -init
-# Strict adopt: re-attach to remote in package.json.repository (or abort)
-npmglobalize -adopt
-# Migrate package.json scripts to use npmglobalize
-npmglobalize -package
-# Preview what would happen
-npmglobalize -dry-run -verbose
-```
-## Authentication
-Requires npm authentication:
-```bash
-npm login
-```
-Check authentication:
-```bash
-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:**
-```bash
-npm run build     # Compile TypeScript files
-npm run watch     # Watch mode for development
-npm run check     # Manually verify build status
-```
-**Bypassing the check:**
-```bash
-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
+# 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
+# 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:
+```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 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:
+```bash
+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):
+```bash
+# 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):
+```bash
+npmglobalize -npd         # --no-publish-deps
+```
+### 🔍 Prescan (Default)
+Before any transform/publish, `npmglobalize` walks the full `file:` dep graph and reports all problems up front (unresolvable paths, missing `package.json`, unscoped packages with private intent, etc.). This lets you fix the whole punch list at once rather than being interrupted mid-cascade.
+Errors abort (unless `--force`); warnings prompt to continue.
+Skip the prescan with `-no-prescan` / `-nps`.
+#### Workspace skip prescan
+In workspace mode, before processing begins, each package is also checked to decide whether it actually needs work. A package is **skipped** (no rebuild, no version bump, no publish) only if **all** of these are true:
+1. **Working tree clean** — `git status --porcelain .` reports no uncommitted changes for that package's directory.
+2. **Version already on npm** — the version in its `package.json` is published to the registry, and no non-bookkeeping commit (anything outside "Pre-release commit" / "Restore file: dependencies" / "Pre-version cleanup" / "Untrack node_modules") is newer than that version's publish timestamp.
+3. **Build is fresh** — every `.ts` source file (excluding `.d.ts`) has a sibling `.js` whose mtime is ≥ the `.ts` mtime. A missing `.js` or an older `.js` counts as stale.
+4. **No sibling workspace `file:` dep flagged for work** — if another workspace package depends on this one via `file:`, and that dep is being updated in this run, this one is also processed (propagates through the graph in topological order).
+If any condition fails, the package is processed. The prescan prints one line per package with `⟳` for "will process" (and the reason) or `✓` for "skip". Example:
+```
+⟳ mlproc     — uncommitted changes
+⟳ pzip       — stale build (index.ts newer than index.js)
+⟳ stage      — dep pzip is being updated
+✓ puller     — skip (clean, published, build fresh)
+```
+The summary row for a skipped package shows `– name v1.0.0 (skipped — already up to date)`.
+Use `--force` or `--force-publish` to bypass the skip prescan and process every package.
+**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
+**Note:** The `--update-deps` flag propagates to all file: dependencies, so one command updates your entire dependency tree.
+### 🔒 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
+```
+### 🧩 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:
+- **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):
+```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
+```
+### 📝 Release Notes via `.commitmsg`
+For multi-line or reusable release notes, write them to a `.commitmsg` file in the package root instead of passing them on the command line:
+```bash
+cat > .commitmsg <<'EOF'
+Added foo feature
+Fixed bar regression
+EOF
+npmglobalize
+```
+Behavior:
+- If `-m` / `-message` is **not** given and `.commitmsg` exists, its contents are used as the commit message (and force a release even if the working tree is otherwise clean).
+- After a successful `npm publish`, npmglobalize:
+  1. Appends the contents to `npmchanges.md` under a `## v<version> — <YYYY-MM-DD>` header (creating the file if needed)
+  2. Deletes `.commitmsg`
+  3. Commits both changes as `Log v<version> to npmchanges.md` and pushes
+Notes:
+- **Git/GitHub only.** npm publish does not consume git commit messages; `npmchanges.md` lives in the git repo and on GitHub but is excluded from the published npm tarball (the standard `*.md` rule keeps only `README.md`).
+- If both `-m` and `.commitmsg` are present, `-m` wins and `.commitmsg` is left alone (not consumed).
+- If publish fails, `.commitmsg` is preserved for the next attempt.
+- `.commitmsg` is auto-added to `.npmignore` (security pattern) so it never leaks into the tarball.
+### 🔧 Git Integration & Error Recovery
+**Automatic tag conflict resolution**:
+```bash
+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:
+```bash
+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:**
+```bash
+npmglobalize -git public     # Makes the GitHub repo public (with confirmation)
+npmglobalize -git private    # Makes the GitHub repo private
+```
+### Missing local `.git` (adopt vs fresh init)
+When npmglobalize runs in a directory with no `.git`, it first checks for a
+reachable `repository.url` in `package.json`. If found, it offers two paths:
+```
+How would you like to set up git?
+  1) Adopt history from existing remote (recommended)
+  2) Initialize fresh git repository
+  a) Adopt ALL (don't ask again for remaining deps)
+  3) Use local install only (skip git/publish)
+  4) Abort
+```
+**Adopt** runs:
+```bash
+git init
+git remote add origin <package.json repository.url>
+git fetch origin
+# Point HEAD at origin/<defaultBranch> without touching the working tree
+git update-ref refs/heads/<branch> origin/<branch>
+git symbolic-ref HEAD refs/heads/<branch>
+git reset                       # mixed: refresh index, keep working tree
+```
+After adoption, your local files appear as **uncommitted changes on top of the
+remote's HEAD** — `git status` shows the drift, and npmglobalize's normal flow
+will commit them on the next publish. **No force-push is required**, and the
+remote's history is preserved.
+If the remote is not reachable (no `repository` field, network/auth failure,
+deleted repo), the original "Initialize fresh git repository" prompt is shown
+instead.
+CLI flags:
+- `-init` — auto path; adopts if a reachable remote is found, otherwise falls
+  back to fresh `git init` + `gh repo create`.
+- `-adopt` — **strict**: aborts if no reachable remote in `package.json.repository`.
+  Use this when you want to be sure no new GitHub repo is created (e.g. in
+  scripts, or when re-attaching a tree of packages to existing repos).
+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):
+```bash
+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.
+### 🔍 HEAD not on a branch — repaired automatically
+Git leaves HEAD "detached" (pointing at a commit rather than at a branch) after checking out a
+commit or a tag, and — far more often in practice — after a `git pull --rebase` that was
+interrupted. The rebase applies its commits, then stops before moving the branch ref, so the
+work exists on a real commit that no branch names.
+npmglobalize repairs that itself rather than stopping and asking you to type git commands. The
+working tree is authoritative, so it:
+1. Clears the unfinished rebase / cherry-pick / revert bookkeeping with `--quit`, which keeps
+   HEAD and the working tree exactly as they are (unlike `--abort`, which would throw away the
+   commits the interrupted run produced).
+2. Moves the branch to the current commit with `git checkout -B <branch>`, and restores its
+   upstream tracking.
+3. Prints what moved, naming the branch and both commits:
+```
+⚠ HEAD is not on a branch — left by an unfinished rebase, at 344431e "Restore file: dependencies"
+  Cleared the unfinished rebase (its commits are kept)
+✓ On branch main at 344431e "Restore file: dependencies"
+  Branch main previously pointed at f3ec2e6 "Pre-release commit", which is not in this history.
+  To put main back there: git reset --hard f3ec2e6
+```
+The branch it picks is, in order: the branch the unfinished rebase was rebuilding (from the
+rebase state), the remote's default branch (`origin/HEAD`), or whichever of `main` / `master`
+the repository actually has. It is never assumed to be `master`.
+**The one case it refuses:** files with unresolved conflict markers. There the working tree is
+not what you meant to publish, so npmglobalize lists the conflicted files and stops.
+## Command Reference
+<!-- NOTE: Keep this in sync with the -help output in cli.ts printHelp().
+     The README expands on options with examples and context;
+     cli.ts is the concise quick-reference. Update both when adding/changing flags.
+     Both -flag and --flag are accepted; single-dash is shown as primary. -->
+### 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)
+                     If -m not given, a `.commitmsg` file (if present) is used instead.
+                     See "Release Notes via .commitmsg" below.
+```
+### Dependency Options
+```
+-update-deps, -ud        Update package.json to latest versions (safe: minor/patch)
+-update-major            Allow major version updates (breaking changes)
+-publish-deps            Auto-publish file: dependencies (default)
+-pd                      Like -publish-deps, plus auto-yes to dep-cascade prompts (private only)
+-no-publish-deps, -npd   Skip auto-publishing file: dependencies
+-no-prescan, -nps        Skip upfront dep-graph prescan
+-force-publish           Republish dependencies even if version exists
+-fix                     Run npm audit fix after transformation
+-no-fix                  Don't run npm audit
+-no-use-paths, -nup      Declare package standalone; do not resolve file: deps
+                         from sibling checkouts (see Configuration File)
+```
+### 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 <values>   Comma-separated list of npm options:
+                  private (default) | public — package visibility
+                  ts                         — keep .ts source (and *.map,
+                                               tsconfig.json) in npm tarball
+                  nts                        — exclude .ts source
+                                               (default for non-noEmit projects)
+                Example: -npm public,ts
+```
+`ts` is already the default on git (source is tracked). Pass `-npm ts` to ship
+the same files to npm — useful for debugging installed packages or "source on
+demand" packages. `noEmit` projects automatically ship `.ts` files (they *are*
+the runtime); pass `-npm nts` to override. `allowTs` persists to
+`.globalize.json5`.
+### 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).
+                If package.json.repository.url is reachable, adopts its
+                history instead of creating a fresh repo.
+-adopt          Strict adopt: require a reachable git remote in
+                package.json.repository. Abort if probe fails. Skips prompt.
+-strict-imports, -import-check
+                Opt in to scanning .ts/.js source for imports of packages not
+                declared in any dependencies bucket. Off by default — the
+                always-declare style this enforces doesn't hold in monorepos
+                that rely on workspace cross-refs or the -public-deps cascade
+                (those produce noisy prompts that get dismissed reflexively,
+                which defeats the safety purpose). Use only on packages where
+                every import is meant to be a direct package.json declaration.
+                When it does fire, it catches silent runtime failures —
+                ERR_MODULE_NOT_FOUND on a clean install of a published tarball
+                that was resolving via an ambient parent/global node_modules
+                at dev time.
+-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
+-clean-nested-modules, -clean-nested
+                Before npm pack, wipe node_modules/ inside each file: dep
+                target. Fixes arborist "Cannot read properties of null"
+                crashes caused by sibling file: deps with nested
+                node_modules. Suggested automatically when the error hits.
+-ts7-report, -deprecation-report
+                Report-only: scan this package and its file: deps for
+                compilerOptions removed in TypeScript 7 and list a migration
+                to-do. Writes nothing.
+-tsfix, -ts7-fix
+                One-off utility, NOT part of the main flow: apply the TS7
+                tsconfig migration to a package (and its file: deps) and exit —
+                no build, no commit, no push, no publish. Intended as a
+                temporary tool for fixing a local/subdirectory tsconfig in
+                place. The normal release flow already applies the same
+                migration automatically when a build hits a TS7 deprecation
+                error, so day-to-day you never need this flag.
+                    npmglobalize <path> -tsfix
+-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:
+```json
+{
+  "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`):
+```bash
+npmglobalize --package       # Sets up "release": "npmglobalize" in package.json
+```
+After that, publishing is just:
+```bash
+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`:
+```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",
+  "usePaths": true           // Resolve file: deps from sibling checkouts (see below)
+}
+```
+Configuration persists across runs. CLI flags override config file.
+### `usePaths` — Standalone packages
+Default: `true`. Set to `false` (or pass `-no-use-paths` / `-nup`) to mark a
+package as **standalone** — one that should be publishable/installable on a
+machine that does not have sibling `file:` dep checkouts available. Example:
+a backup/recovery utility you want to `npm install -g` on any host.
+Currently this setting is **declarative** — it is parsed, persisted to
+`.globalize.json5`, and surfaced in the settings banner, but the tool does
+not yet change its behavior based on it. Behavior wiring (e.g. resolving
+`file:` deps to the latest published npm version instead of walking siblings)
+is planned.
+### `upstream` — who consumes this package
+**Experimental.** Bookkeeping, not a setting. When a package with `file:` deps
+publishes, npmglobalize appends an entry to each **dependency's**
+`.globalize.json5`:
+```json5
+{
+  "install": true,
+  // FYI: packages that depend on this one (immediate consumers,
+  //      recorded when each of them publishes). Nothing is updated
+  //      automatically; follow each path's own .globalize.json5 to
+  //      walk further out.
+  "upstream": [
+    {"path":"Y:\\dev\\utils\\winpos","version":"2.0.51","updated":"2026-08-09"},
+  ],
+}
+```
+So publishing `winpos` (which has `"@bobfrankston/msger": "file:../msgx/msger"`)
+records winpos in **msger's** config. Each entry carries the consumer's
+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.
+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
+### 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. **Checks** if current version is on npm (recovers from failed publishes)
+3. **Updates dependencies** (if `--update-deps`)
+4. **Builds `file:` deps in topological order**, then the target itself, so consumers' `tsc` reads up-to-date `.d.ts` from sibling checkouts whose source has changed (see [Build Cascade](#build-cascade))
+5. **Publishes file: dependencies** (if needed)
+6. **Backs up** original file: references to `.dependencies`
+7. **Converts** `file:` → npm version references
+8. **Commits** changes
+9. **Bumps** version (using npm version) — skipped if recovering a failed publish
+10. **Publishes** to npm
+11. **Pushes** to git (with push-protection detection and auto-bypass)
+12. **Installs** globally (if `--install`)
+13. **Restores** file: references (if `--files`, default)
+14. **Runs audit** (shows security status)
+## Operational Details
+### Build Cascade
+Before transforming or publishing anything, `npmglobalize` builds `file:` dependencies in topological order — deps before consumers — and then builds the target itself. This guarantees the target's `tsc` reads up-to-date `.d.ts` and `.js` from sibling checkouts even when a dep's source has changed since its last build.
+For each project visited (the target and every transitive `file:` dep):
+- If `tsconfig.json` is missing or has `"noEmit": true` → **skip** (not a TypeScript build), unless the `build` script runs `importgen` — a plain-JS browser app still needs its import map regenerated.
+- If `tsconfig.json` exists but `package.json` has no `"build"` script → **prompt** to add `"build": "tsc"` (plus a `tsc -p <dir>` per sub-project — see below). Decline and that project is skipped.
+- Otherwise → run `npm run build`. A failure halts the cascade unless `-force` is passed.
+Cycle-safe via a shared visited set; each project is built at most once per run.
+This complements the existing publish cascade (which ensures version refs are correct) by closing the build-freshness gap that `npm install` alone left open.
+#### Import maps (`importgen`) as a build step
+Browser projects that use [`importgen`](https://www.npmjs.com/package/@bobfrankston/importgen) have historically regenerated their import map from `.vscode/tasks.json`, which only runs when VS Code opens the folder — so a command-line or CI build could publish a stale map. `npmglobalize` treats the import map as a build product and moves the step into the package's own `build` script, where every build path picks it up.
+Before building each project, it checks whether the project is an importgen project, in this order:
+1. `.vscode/tasks.json` has a task whose `command` is `importgen` (the HTML file, if the task names one, is reused).
+2. A root-level `.htm`/`.html` file already contains a `<script type="importmap">` block (`index.html`, `default.html`, `default.htm` are checked first, so a stray `temp.htm` doesn't win).
+3. `importgen` is in `dependencies`/`devDependencies` **and** the project has one of those HTML files — the HTML requirement keeps packages that merely *use* importgen as a library from matching.
+If a signal matches and the `build` script doesn't already run `importgen`, you're prompted to rewrite it — e.g. `"build": "tsc"` → `"build": "importgen default.htm && tsc"`. The HTML file is named explicitly so importgen doesn't have to guess. Decline and `"importgen": false` is written to `.globalize.json5`, which suppresses the prompt for good; `-noimportgen` does the same from the command line.
+Once wired, the freshness check gains a second condition: a project whose build runs importgen is only considered up to date if the generated HTML is at least as new as `package.json`. Adding a dependency changes the import map without touching any `.ts` file, which the source-vs-output comparison alone would miss.
+#### Sub-projects (a second `tsconfig.json` in a sub-directory)
+A package can hold more than one TypeScript project. The common shape is a service worker in `Sw/` with its own `tsconfig.json` (`lib: ["WebWorker"]`, its own `outDir`) that the root `tsconfig.json` lists under `exclude` — so a bare `"build": "tsc"` compiles everything *except* the service worker, and the stale `sw2.js` ships. As with import maps, these have historically been built only by a second `.vscode/tasks.json` watcher, which runs on folder open and nowhere else.
+Before building, `npmglobalize` looks for sub-projects, in this order:
+1. `.vscode/tasks.json` has a task that runs `tsc` with `"options": { "cwd": "${workspaceFolder}/Sw" }` or with `-p`/`--project` naming a sub-directory (authoritative — it's how the project is actually built today; the task's `label` is quoted back in the prompt).
+2. An immediate sub-directory containing its own `tsconfig.json`. Build output and vendored trees (`node_modules`, `prev`, `dist`, `built`, `out`, `wwwroot`, `coverage`, `temp`, `preflight`, dot-directories) are never scanned.
+Nothing is detected when the root `tsconfig.json` uses project `references` — that build graph belongs to `tsc -b` and isn't second-guessed.
+When the `build` script is `tsc`-driven and doesn't already compile a detected sub-project, you're prompted to append it — `"build": "tsc"` → `"build": "tsc && tsc -p Sw"`, or for an importgen project `"build": "importgen default.htm && tsc && tsc -p Sw"`. Already-wired scripts are recognized in any of their spellings (`tsc -p Sw`, `tsc --project ./Sw/tsconfig.json`, `cd Sw && tsc`), and the directory is emitted with its real on-disk casing so the script still works on WSL and CI. Decline and `"subProjects": false` is written to `.globalize.json5`, suppressing the prompt for good; a `"subProjects": ["Sw"]` array pins the list instead of detecting it.
+Sub-projects the build actually compiles are also folded into the freshness check — the package rebuilds when a sub-project's sources are newer than its output. A sub-project that emits *outside* its own directory (`"outDir": ".."`, the usual service-worker case) always reports stale: comparing its sources against the whole package would prove nothing.
+#### TypeScript 6 `types` auto-fix
+TypeScript 6 dropped the legacy behavior of auto-including every installed `@types/*` package. A `tsconfig.json` with no explicit `compilerOptions.types` then loses the Node globals (`process`, `Buffer`, …) and the build fails with `TS2591`.
+Before each build, when the global `tsc` is version 6 or newer, `npmglobalize` patches the project's `tsconfig.json` to add an explicit `types` list — enumerating the installed `@types/*` packages (e.g. `"types": ["node", …]`) — restoring the old behavior. The edit is:
+- **Conservative** — only applied when `compilerOptions.types` is **absent**, `node_modules/@types/node` is actually installed, and there is no `extends` (whose merged `types` can't be seen). An explicit `types` you already set is never overridden.
+- **Format-preserving** — the single `types` key is inserted into the existing `compilerOptions` block; comments, ordering, and indentation are left intact.
+- **Idempotent** — once the list is present, subsequent runs skip it.
+If the patch can't be applied for some reason and the build still fails with `TS2591`, the failure summary prints a hint to add `"types": ["node"]` manually.
+### 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:
+```bash
+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:
+```bash
+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:
+```bash
+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
+```bash
+# 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 git (adopt existing remote if reachable, else fresh) + release
+npmglobalize -init
+# Strict adopt: re-attach to remote in package.json.repository (or abort)
+npmglobalize -adopt
+# Migrate package.json scripts to use npmglobalize
+npmglobalize -package
+# Preview what would happen
+npmglobalize -dry-run -verbose
+```
+## Authentication
+Requires npm authentication:
+```bash
+npm login
+```
+Check authentication:
+```bash
+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:**
+```bash
+npm run build     # Compile TypeScript files
+npm run watch     # Watch mode for development
+npm run check     # Manually verify build status
+```
+**Bypassing the check:**
+```bash
+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