reloc

Rescope and relocate npm packages across a dev tree.

Handles renaming unscoped packages (e.g., dbx10 -> @bobfrankston/dbx10) and moving package directories to new locations, updating all file: references and .ts imports in consumers.

Install

npm install -g @bobfrankston/reloc

Modes

-bridge (gradual migration)

Creates a copy of the package with the new scoped name, archives the original to prev/, and leaves a re-export shim in the original location. Existing consumers keep working via the shim while you migrate them one at a time.

reloc dbx10 @bobfrankston/dbx10 -bridge

What happens:

1. Copies dbx10/ to dbx10b/ with name @bobfrankston/dbx10
2. Archives original dbx10/ to prev/dbx10-MMDDYY
3. Creates a shim at dbx10/ that re-exports from @bobfrankston/dbx10
4. Writes consumers.txt in the bridge dir listing all consumers

Use -target <dir> to override the bridge directory (default: <olddir>b).

-inplace (rename in place)

Renames the package in its existing directory. No bridge, no shim. Consumers break until migrated.

reloc dbx10 @bobfrankston/dbx10 -inplace

-scan

Finds all consumers of a package across directory trees and writes consumers.txt.

reloc dbx10 @bobfrankston/dbx10 -scan
reloc dbx10 @bobfrankston/dbx10 -scan -dirs y:\dev\homecontrol

-apply <dir>

Migrates consumers to the package in <dir>. Reads old/new names from consumers.txt in that directory. For each consumer: uninstalls old name, installs new name (preserving file: paths), updates .ts imports, recompiles.

reloc -apply y:\dev\homecontrol\utils\dbx10b -dirs y:\dev\homecontrol

Requires -dirs to specify which trees to scan/migrate.

-back <dir>

Reverses a bridge. Moves real code from the bridge dir back to the original location, bridge becomes a shim. Generates consumers.bat to reinstall in each consumer.

reloc -back y:\dev\homecontrol\utils\dbx10b

<dir> must end in b (the bridge convention).

-move <from> <to> [newname]

Preview moving a package directory. Shows what consumers have file: refs pointing to the old location and what paths would change. Dry run by default.

reloc -move y:\dev\projects\nodejs\sql\sqllib y:\dev\projects\sql\sqllib
reloc -move y:\dev\projects\nodejs\sql\sqllib y:\dev\projects\sql\sqllib @bobfrankston/sqllib

If the package name is unscoped (no @), a warning is shown since rescoping is often the reason for a move.

-apply-move <from> <to> [newname]

Actually executes the move: copies to new location, updates all file: refs in consumers, generates cleanup.bat (archive old dir after reboot) and reinstall.bat (npm install in each consumer).

reloc -apply-move y:\dev\projects\nodejs\sql\sqllib y:\dev\projects\sql\sqllib
reloc -apply -move y:\dev\projects\nodejs\sql\sqllib y:\dev\projects\sql\sqllib
reloc -move y:\dev\projects\nodejs\sql\sqllib y:\dev\projects\sql\sqllib -apply

-apply and -move can be separate flags in any order — they combine to mean "live move". -apply-move as a single flag also works.

If [newname] is provided, also renames the package (updates name in package.json, renames dep keys in consumers, updates .ts imports).

Options

| Option | Description | |--------|-------------| | -dirs <d1> [d2 ...] | Directory trees to scan/migrate (default: y:\dev) | | -target <dir> | Override bridge directory (default: <olddir>b) | | -tree <dir> | Root of dev tree (default: y:\dev) | | -verbose, -v | Show detailed output | | -help, -h | Show help |

Workflow Example

Rescoping dbx10 to @bobfrankston/dbx10 across a large tree:

# 1. Create bridge (copies package, archives original, leaves shim)
reloc dbx10 @bobfrankston/dbx10 -bridge

# 2. Migrate one subtree at a time
reloc -apply y:\dev\homecontrol\utils\dbx10b -dirs y:\dev\homecontrol\utils
reloc -apply y:\dev\homecontrol\utils\dbx10b -dirs y:\dev\homecontrol\Others

# 3. When all consumers migrated, reverse the bridge
reloc -back y:\dev\homecontrol\utils\dbx10b

# 4. Run the generated consumers.bat to npm install everywhere

Key Behaviors

• Dry run by default for -move and -scan. Use -apply or -apply-move to execute.
• Idempotent: skips consumers already using the new name; cleans up stale old-name entries.
• Preserves file: refs: when renaming deps, the relative path is recomputed, not lost.
• Honors noEmit: projects with noEmit: true in tsconfig skip the tsc step (e.g., bun projects).
• Skips generated files: when copying, .js, .d.ts, .map files are skipped if a corresponding .ts source exists.
• Skips node_modules/, prev/, .git/, cruft/ when scanning.
• Marks consumers.txt: ✓ for success, ✗ with error note for failures.

Files Generated

| File | When | Purpose | |------|------|---------| | consumers.txt | -bridge, -scan | Lists all consumers with status marks | | consumers.bat | -back | Reinstalls package in each consumer | | cleanup.bat | -apply-move | Archives old directory after reboot | | reinstall.bat | -apply-move | Runs npm install in each consumer |