Skip to content

feat(utils): add Windows nodeenv migration helper - #452

Open
danilovmy wants to merge 3 commits into
ekalinin:masterfrom
danilovmy:codex/windows-nodeenv-migration
Open

danilovmy wants to merge 3 commits into
ekalinin:masterfrom
danilovmy:codex/windows-nodeenv-migration

Conversation

@danilovmy

@danilovmy danilovmy commented Oct 29, 2026 •

Copy link
Copy Markdown

Motivation

In an existing project with both Python and Node.js, I wanted activating the
Python virtual environment to also select the project's already installed
Node/npm. The runtimes had been set up separately, so consolidating them meant
manually moving files without replacing the Python activation scripts and then
editing activation and deactivation for each Windows shell.

This adds an optional, repeatable utility for that migration: simply add an
existing Node installation to an existing Python environment, reuse the installed
files, and use one activation entry point for both runtimes.

For a new setup, nodeenv -p is strongly recommended. Create and activate the
Python venv first, then run nodeenv -p. The new utility is for consolidating
environments that already exist, without downloading Node/npm again.

Changes

  • Add utils/integrate_nodeenv.py with --source, --venv and --dry-run.
    Defaults are env and .venv in the project's current working directory.
  • Move missing files and directories while preserving existing destination
    entries and retaining their source copies. Reject overlapping roots,
    incompatible file/directory collisions and unsafe activation links.
  • Validate all four activation files before moving anything, then integrate
    NODE_PATH save/restore into CMD, PowerShell and Git Bash activation and
    deactivation. Repeated runs preserve existing recognized patches and mtimes.
  • Keep the source directory until the user removes it. Report that it can be
    deleted only after migration and patching both succeed.
  • Document the motivation, recommended nodeenv -p workflow and migration steps
    in utils/README.md; link it from the main README and add a changelog entry.
  • Cover the helper with offline tests and include utils in flake8 checks.

The utility is Windows-only, runs on Python 3.10+, and accepts recognized CPython
activation layouts. It preserves UTF-8 BOMs and line endings. An edited
Activate.ps1 loses its original signature; execution policy is left unchanged.

Validation

Tested locally on Windows with Python 3.12.10 and Git Bash available on PATH:

coverage run -p -m pytest -m 'not integration' tests -q
349 passed, 157 skipped, 11 deselected

flake8 --extend-ignore=E127 nodeenv.py tests setup.py utils
Passed

git diff --check
Passed

The 40 new tests cover migration/no overwrite, dry runs, preflight failures,
repeated runs, working-directory defaults, junction handling, platform checks,
line endings, BOMs and PowerShell signatures. Download-based integration tests
were excluded from the local run.

  • Tests cover the change.
  • Tests and flake8 pass using the direct commands from CONTRIBUTING.md.
  • CHANGES has an entry under Version [unreleased].
  • README.rst and utils/README.md describe the workflow.
  • The title follows type(scope): subject.

@ekalinin

Copy link
Copy Markdown
Owner

Please rebase on master.

@danilovmy
danilovmy force-pushed the codex/windows-nodeenv-migration branch from f79bb4f to 62783ba Compare October 30, 2026 12:25
@danilovmy

Copy link
Copy Markdown
Author

Rebased.

@ekalinin ekalinin left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the patch! Three things before merge.

  • The anchors match only the newest CPython venv templates. activate.bat has the quoted set "PATH=%VIRTUAL_ENV%\Scripts;%PATH%" in 3.12.10, 3.13.5 and later, but 3.10, 3.11, 3.12.0-3.12.7 and 3.13.0 write it without quotes. The bash activate has # Call hash to forget past locations. in the same versions, while older ones say # Call hash to forget past commands. or # This should detect bash and zsh. For a venv made by any of those, the utility stops with expected one insertion point, though the README says Python 3.10+. I ran patch_activation on the templates from the CPython tags: 3.10.11, 3.11.9, 3.12.0, 3.12.7 and 3.13.0 fail, 3.12.10, 3.13.5, 3.13.9 and 3.14.0 pass. The test fixtures are hand-written excerpts, so they don't catch it.

    The inserted blocks also differ from what nodeenv puts into these scripts. They never set npm_config_prefix, so #309 comes back in a migrated venv: npx exports a prefix and Scripts\npm.cmd then runs the npm found under it. In Git Bash they clear NODE_PATH, while nodeenv's activate sets it to Scripts/node_modules.

    nodeenv can already do this part. Since 1.11.0, nodeenv -p .venv --node=<version> skips the download when that node version is already in the venv (#403), and then appends its own blocks to activate, activate.bat, deactivate.bat and Activate.ps1, including the PowerShell signature handling. So the utility could move the files and then run that command with the installed version (or the README could tell the user to run it), and PATCHES and patch_activation with their tests can go. I checked it on macOS with a venv that already held node 26.13.0: nothing was downloaded, and activate got the NODE_PATH and npm_config_prefix blocks. I haven't tried it on Windows.

  • If a rename fails halfway, for example because an editor or a dev server holds node.exe or a file under node_modules, the entries moved before it stay in .venv, the activation scripts are not changed, and neither environment works. Please move them back on failure, or at least list what was moved in the error. Also, "You can now delete the source directory" is printed when skipped > 0 too. The files kept in env are not compared with those in .venv, so the user can be told to delete the only copy of a different node.exe. I'd print it only when nothing was skipped, and list the skipped entries otherwise.

  • README.rst is also the PyPI description (setup.py reads it), and the relative link utils/README.md doesn't resolve on pypi.org. A full GitHub URL works in both places.

@danilovmy
danilovmy force-pushed the codex/windows-nodeenv-migration branch from 92325ef to 526958c Compare November 15, 2026 18:28
@danilovmy

danilovmy commented Nov 15, 2026 via email •

Copy link
Copy Markdown
Author

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Active issues can leave Python activation unvalidated, mix or duplicate CRLF activation patches, and leave Node environment variables set after normal Python deactivation.

3 open issues
What changed in this PR

Adds an optional Windows migration helper for consolidating an existing Node environment into a Python venv, complementing the recommended nodeenv -p workflow for new setups.

Changes:

  • Adds migration planning, collision checks, dry-run output, move rollback, and activation through nodeenv -p.
  • Adds offline tests for migration behavior and failure handling.
  • Documents the workflow and includes utils in lint checks.
File Description
utils/​README.md Documents migration usage, prerequisites, and limitations.
utils/​integrate_nodeenv.py Implements the Windows migration helper.
tox.ini Adds utilities to tox lint checks.
tests/​test_integrate_nodeenv.py Tests migration planning, safety checks, and failures.
README.rst Links to the optional migration workflow.
CONTRIBUTING.md Updates the documented lint command.
CHANGES Announces the migration utility.
.github/​workflows/​tests.yml Includes utilities in CI lint checks.

Review effort: Balanced

Comment on lines +101 to +104
subprocess.run([
sys.executable, str(nodeenv), '-p', str(destination),
f'--node={version[1]}', '--config-file=', '--no-clean-src',
], check=True)

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed in e9c77a1

Comment on lines +101 to +104
subprocess.run([
sys.executable, str(nodeenv), '-p', str(destination),
f'--node={version[1]}', '--config-file=', '--no-clean-src',
], check=True)

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed in e9c77a1

Comment thread utils/integrate_nodeenv.py Outdated
Comment on lines +143 to +147
for name in ('activate', 'activate.bat', 'deactivate.bat',
'Activate.ps1', 'predeactivate.bat', 'predeactivate.ps1'):
existing = resulting_file(scripts / name)
if os.path.lexists(existing):
if is_link(existing) or not existing.is_file():

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed in e9c77a1

@danilovmy

Copy link
Copy Markdown
Author

I change this three problem from Copilot. I am agree with this comments. It is hard to check all use cases once.

  • Activation scripts preserve LF or CRLF. Rerunning the migration no longer duplicates existing activation blocks.
  • In Git Bash, the standard deactivate now deactivates both Python and Node.
  • The migration validates activation scripts in the destination venv BEFORE moving any files.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants