Repository navigation
Description
#736 is merged (feb6092) and released in v1.1.0, together with #738 (baseline is now the default path.mode) and #739 (vfox config writes only the key it sets). It added vfox link, vfox doctor, vfox alias, installation receipts, the optional Fingerprint and Detect hooks, PLUGIN.shadowHints and the path.mode setting.
This issue collects what is left, so that each item can be picked up, discussed or dropped on its own. #736 closed #706 and #669. Update 2026-11-10, verified against main at v1.1.0 (3682fe8) plus the plugin releases of today (gradle v0.1.3, java v0.6.6, nodejs v0.5.6, flutter v0.2.6, golang v0.4.3) and the template PR merge (version-fox/vfox-plugin-template#12): #670 and #359 are closed (aliases are in, see 1); #337 is closed COMPLETED by the baseline default and only #732 stays open, pending a Windows re-test with baseline as the default (see 1); 3 and 4 are done; in 2, flutter/nodejs/java/template are done (template release pending in version-fox/vfox-plugin-template#13); 5 is still open.
1. Release
- Release vfox with feat: link existing SDKs, add vfox doctor, aliases and path.mode #736. The plugin work below needs it. Done in v1.1.0 (
3682fe8, 2026-11-07), which also includes feat(config): make baseline the default path.mode #738, fix(config): make vfox config write only the key it sets #739, feat: add install --use to switch to the version just installed #740, fix(upgrade): check the install directory is writable before upgrading on Unix #742, fix: align current output and uninstall version spelling #744, fix: name the status of a refused download, hide URL credentials in messages, update via manifestUrl #747, fix: refresh the env cache on legacy file, install, link and config changes; keep project versions off the global link and version #748. - Release notes: the new commands (
link,doctor,alias), thepath.modesetting with the advice to runvfox config path.mode baseline, and the planned change of the default (3). Done in the sense that v1.1.0 shipped all three changes, but the v1.1.0 notes are the auto-generated changelog and do not spell out the new commands / the one-line way back (vfox config path.mode legacy). Follow-up is optional. - After the release, point [BUG]: some of the packages are not changing accordingly #337 and [BUG]: On Windows,
vfox use java@Xdoesn't changejavawhen a JDK is in the system PATH and a global SDK is set #732 topath.mode baseline, and decide what is left of [Feature]: 支持为已安装的 SDK 版本添加别名/重命名功能 #670 and [Feature]: alias | Alias a version to a common name #359. Aliases are resolved on the command line only and are never written to.vfox.toml, so the second scenario in [Feature]: 支持为已安装的 SDK 版本添加别名/重命名功能 #670, an alias shared through the version file, is not covered. That was on purpose: a teammate without the alias would get an "is not installed" that vfox cannot explain. Done 2026-10-23: [Feature]: 支持为已安装的 SDK 版本添加别名/重命名功能 #670 and [Feature]: alias | Alias a version to a common name #359 areCOMPLETED, [BUG]: some of the packages are not changing accordingly #337 and [BUG]: On Windows,vfox use java@Xdoesn't changejavawhen a JDK is in the system PATH and a global SDK is set #732 got apath.mode baselinecomment. Update 2026-11-10: [BUG]: some of the packages are not changing accordingly #337 is closedCOMPLETED(baselineis now the default via feat(config): make baseline the default path.mode #738, released 2026-11-07). Left: re-test [BUG]: On Windows,vfox use java@Xdoesn't changejavawhen a JDK is in the system PATH and a global SDK is set #732 withbaselineas the default in v1.1.0 and decide what remains.
2. Plugins
The new hooks are optional. Older vfox versions (checked: 0.6.0, 1.0.0 and 1.0.13) never load a hook file they do not know and skip metadata fields they do not know, so a plugin can add them without raising minRuntimeVersion. For plugin authors: Fingerprint, Detect and shadowHints.
Verified 2026-11-10: flutter, nodejs, java and template are done (see below; template release pending in version-fox/vfox-plugin-template#13).
- vfox-flutter: replace the plugin's own drift detection with a
Fingerprinthook. Done in v0.2.6 (feat: report drift via Fingerprint hook vfox-flutter#55):hooks/fingerprint.luareports the SDK checkout's git HEAD from files only, vfox records it in the receipt and reportssdk.driftaftervfox useand invfox doctor(fixed withvfox install --reinstall);hooks/pre_use.luastays quiet on vfox 1.1.0+ and keeps the legacy.vfox-manifestwarning for older vfox behind aRUNTIME.versiongate, sominRuntimeVersionstays 0.3.0.docs/flutter-upgrade.md(and the zh-CN copy) updated to match. - vfox-nodejs: replace
util.shadowing_node()and theNote:thathooks/pre_use.luaprints withPLUGIN.shadowHints(the pnpm explanation and the link todocs/pnpm.md). Done in v0.5.5 (feat: report shadowing node via PLUGIN.shadowHints vfox-nodejs#48): declaresPLUGIN.shadowHints, stays quiet on vfox 1.1.0+ (the core warns and appends the hint) and keeps theNote:for older vfox viautil.supports_shadow_hints(). Bonus in the same release:hooks/detect.lua, sovfox link --detect nodejsfinds nvm/mise/asdf/Homebrew/winget installs. v0.5.6 (fix: follow .nvmrc/.node-version both ways on vfox 1.1.0, drop the env-state workaround; docs vfox-nodejs#50) additionally drops the env-state workaround for.nvmrc/.node-versionand needs vfox >= 1.1.0 ([BUG]:vfox envserves the cached output after acd: a .nvmrc / .node-version is ignored on the way in and kept on the way out #745/fix: refresh the env cache on legacy file, install, link and config changes; keep project versions off the global link and version #748). - vfox-java: add a
Detecthook, so thatvfox link --detect javafinds the JDKs that are already on the machine (Use pre-existing JDK installations #706, [Feature] 支持导入 Ubuntu/Debian 上由 update-alternatives 管理的现有工具版本 #669). Done in v0.6.6 (feat: add Detect hook, so that vfox link --detect java finds existing JDKs vfox-java#128, closes [Feature]: ADetecthook, so thatvfox link --detect javafinds the JDKs that Gradle, IDEs and package managers put on the machine vfox-java#127): scans Gradle's jdks folder, IntelliJ IDEA's folder, system directories, SDKMAN/asdf/mise/jabba, Homebrew kegs, Scoop, the CI runner tool cache andJAVA_HOME; names versions like install does (<runtime>-<short implementor>[-fx], GraalVM's own version for that family); opt-in IDEA links behindVFOX_JAVA_JDKS_LINKS=1. - vfox-plugin-template:
hooks/had the seven older hooks only. Done in feat: add optional fingerprint/detect examples and shadowHints vfox-plugin-template#12 (merged 2026-11-10,4a1275b): adds optionalfingerprint.luaanddetect.luaexamples and a commentedPLUGIN.shadowHintsinmetadata.lua. Release pending in Release a new version with fingerprint/detect/shadowHints examples vfox-plugin-template#13. - Where a plugin stops doing something itself (flutter's check, nodejs's PATH scan), decide between raising
PLUGIN.minRuntimeVersionand keeping the old code for older vfox, which the plugin can tell fromRUNTIME.version. Where it only adds a hook, no bump is needed. Decided in practice: no plugin raisedminRuntimeVersion(flutter, nodejs, gradle and the template stay at 0.3.0, java and golang at the 0.4.0 they already had); flutter and nodejs keep the old code for older vfox behind aRUNTIME.versiongate; pure hook additions needed no bump.
Per-plugin issues can be opened in the plugin repositories and linked here. Beyond the four above, also released today: vfox-golang v0.4.3 (version-fox/vfox-golang#26: Detect + shadowHints) and vfox-gradle v0.1.3 (version-fox/vfox-gradle#8: Detect + shadowHints + Fingerprint + parse_legacy_file). Python Detect is the obvious remaining candidate.
3. Change the default of path.mode to baseline
Done in #738, released in v1.1.0. config.DefaultPathMode is baseline; EmptyPath, both fallbacks of EffectiveMode, and the starting mode of pathPolicy() use it. Docs (EN + zh-hans), internal/sdk/check.go hints, and the AGENTS.md bullet are updated.
- Decide the release, and whether an earlier release should warn first, for instance with a notice from
vfox doctorwhilepath.modeis not set explicitly. Decided: shipped directly in v1.1.0 (feat(config): make baseline the default path.mode #738,dfd5782, 2026-11-07), no warning release. - Code:
EmptyPathininternal/config/path.go, the two fallbacks inEffectiveMode(they returnlegacyfor an empty or an unknown value; decide whether a typo should land on the new default) and the starting mode inpathPolicy()ininternal/env/pathpolicy.go. A throw-away flip of these fails 11 tests incmd/commands,internal/config,internal/envandinternal/sdk, which assert the old default. Done: typo/empty fall back to the new default (DefaultPathMode), tests updated in feat(config): make baseline the default path.mode #738. - Docs, English and zh-hans: drop the announcements and the "set baseline" step in
docs/guides/quick-start.mdand both READMEs, updatedocs/guides/configuration.mdanddocs/guides/faq.md, and say how to keep the old behavior (vfox config path.mode legacy). Also the bullet inAGENTS.mdthat sayslegacystays the default. Done in feat(config): make baseline the default path.mode #738 (quick-start no longer mentionspath.mode; configuration guide documentsbaseline (the default)andvfox config path.mode legacy;AGENTS.mdsaysbaseline, the default). - The hints of the
path.shadowedfinding ininternal/sdk/check.gosuggestvfox config path.mode baseline. Reword them. Done: hints now distinguishlegacyvs post-activation additions / missing baseline. - Release notes: say it first, with the one-line way back. Done in the sense that feat(config): make baseline the default path.mode #738 is the first feature entry of v1.1.0; the one-line way back (
vfox config path.mode legacy) lives in the configuration guide, not in the release notes.
To keep in mind: a shell that was started before the upgrade has no recorded baseline and keeps behaving like legacy until it is restarted. A directory that has to stay in front of vfox's can be listed in path.preserve. vfox doctor says what shadows a command and why.
4. vfox config should write only the key it sets
Done in #739, released in v1.1.0.
Before #739, vfox config <key> <value> loaded the merged shared and user configuration and saved all of it into the user's config.yaml. The user's file then held a copy of every section, the shared aliases included, and since a section that the user's file declares replaces the shared one, a later change of the shared configuration no longer applied. --unset wrote the default value instead of removing the key. vfox alias already edited only its own key (config.AliasFile).
- Edit the user's file as a YAML document and touch only the key that is set or unset, keeping the other keys and the comments.
config.AliasFilecan be generalized for this. Done in fix(config): make vfox config write only the key it sets #739 (5057618). -
--unsetremoves the key, so that the shared value or the default applies again. Done in fix(config): make vfox config write only the key it sets #739. - Tests: with a shared config present, setting one key copies nothing else. Done in fix(config): make vfox config write only the key it sets #739.
5. Smaller items
Verified 2026-11-10: both still open.
- CI has no Nushell, so the generated
vfox.nuis only checked as text. Add a job that installs Nushell, sources the script and checks thatvfox envsees__VFOX_ORIG_PATH. It was checked by hand with Nushell 0.116.1 for feat: link existing SDKs, add vfox doctor, aliases and path.mode #736. - The CLI-level tests in
cmd/commands(cliFixtureincli_test.go) skip on Windows, where only the unit tests and the E2E workflow run. Make the fixture work there, so that the junction,.cmdand PATH separator cases are covered end to end as well.
6. Open questions from the description of #736
Shipped in v1.1.0, so decided by release unless somebody reopens them:
- The names
Fingerprint,Detect,shadowHintsand.vfox-receipt.json— kept. - Whether the warning after
vfox usemay be on by default (diagnostics.onUse) — yes,EmptyDiagnostics.OnUsedefaults totrue. - Whether
Detectbelongs in the core or in the plugins — in the plugins (vfox link --detectcalls the plugin hook; shipped on 2026-11-10 in vfox-golang v0.4.3, vfox-nodejs v0.5.5, vfox-java v0.6.6 (the request: [Feature]: ADetecthook, so thatvfox link --detect javafinds the JDKs that Gradle, IDEs and package managers put on the machine vfox-java#127, closed) and vfox-gradle v0.1.3).
Activity
linghengqian commentedon Oct 22, 2026
I am working on the current issue.
feat(config): make baseline the default path.mode (#738)
fix(config): make vfox config write only the key it sets (#739)
linghengqian commentedon Nov 10, 2026
Update 2026-11-10, verified against
mainat v1.1.0 (3682fe8):Done since the issue was opened:
COMPLETED(2026-10-23); [BUG]: some of the packages are not changing accordingly #337 and [BUG]: On Windows,vfox use java@Xdoesn't changejavawhen a JDK is in the system PATH and a global SDK is set #732 got thevfox config path.mode baselinecomment (2026-10-23).path.mode(feat(config): make baseline the default path.mode #738,dfd5782). Code (DefaultPathMode,EmptyPath,EffectiveModefallbacks,pathPolicy()), docs (quick-start, configuration EN + zh-hans, faq, READMEs),internal/sdk/check.gohints, and theAGENTS.mdbullet are updated.vfox configwrites only the key it sets/unsets (fix(config): make vfox config write only the key it sets #739,5057618).diagnostics.onUsedefaults totrue,Detectstays in plugins.Still open:
Fingerprint(stilllib/manifest.lua+pre_usewarning), nodejsshadowHints(stillutil.shadowing_node()+Note:), javaDetect(tracked in [Feature]: ADetecthook, so thatvfox link --detect javafinds the JDKs that Gradle, IDEs and package managers put on the machine vfox-java#127, open, prototype only, no PR), template examples (hooks/still the seven old hooks). Plus theminRuntimeVersionvs old-code decision.vfox.nu/__VFOX_ORIG_PATH; WindowscliFixture(cmd/commands/cli_test.gostill skips).vfox use java@Xdoesn't changejavawhen a JDK is in the system PATH and a global SDK is set #732 are stillOPEN— re-test them withbaselineas the default in v1.1.0 and close or narrow them. The v1.1.0 notes are the auto-generated changelog; the longer new-command /path.modewrite-up from the issue was not included.The issue description is updated accordingly (1/3/4/6 marked done, 2/5 left open).
feat: add Detect hook, so that vfox link --detect java finds existing…
feat: add Detect hook, so that vfox link --detect java finds existing…
feat: add Detect hook so vfox link --detect nodejs finds existing ins…
feat: add Detect hook, so that vfox link --detect java finds existing…
feat: report shadowing node via PLUGIN.shadowHints (#48)
feat: add Detect hook and opt-in IDEA links for installed JDKs
feat: add Detect hook and opt-in IDEA links for installed JDKs (#128)
feat: adapt to vfox 1.1.0 with Detect hook and shadowHints (#8)
linghengqian commentedon Nov 10, 2026
Update 2026-11-10, after today's plugin releases (verified against each repo's
main):Done since the last update:
Fingerprinthook reporting the SDK checkout's git HEAD, legacy.vfox-manifestwarning kept for older vfox behind aRUNTIME.versiongate,flutter-upgradedocs (EN + zh-CN) updated.PLUGIN.shadowHints, quiet on vfox 1.1.0+ (the core warns and appends the hint),Note:kept for older vfox viautil.supports_shadow_hints(); bonus in the same release:hooks/detect.lua(vfox link --detect nodejs). v0.5.6 (fix: follow .nvmrc/.node-version both ways on vfox 1.1.0, drop the env-state workaround; docs vfox-nodejs#50) drops the env-state workaround for.nvmrc/.node-versionand needs vfox >= 1.1.0 ([BUG]:vfox envserves the cached output after acd: a .nvmrc / .node-version is ignored on the way in and kept on the way out #745/fix: refresh the env cache on legacy file, install, link and config changes; keep project versions off the global link and version #748).Detecthook, so thatvfox link --detect javafinds the JDKs that Gradle, IDEs and package managers put on the machine vfox-java#127):Detecthook, versions named like install does (<runtime>-<short implementor>[-fx], GraalVM's own version for that family), opt-in IDEA links behindVFOX_JAVA_JDKS_LINKS=1.Detect+shadowHints(gradle alsoFingerprint+parse_legacy_file).minRuntimeVersiondecision: all four plugins kept 0.3.0 and gated the old code viaRUNTIME.version; pure hook additions needed no bump.COMPLETEDby thebaselinedefault (feat(config): make baseline the default path.mode #738).Still open:
fingerprint.lua/detect.lua/shadowHints); pythonDetectis the obvious remaining candidate.vfox.nu/__VFOX_ORIG_PATH, and the WindowscliFixture(cmd/commands/cli_test.gostill skips).vfox use java@Xdoesn't changejavawhen a JDK is in the system PATH and a global SDK is set #732 still waits on a Windows check against v1.1.0; [BUG]: A download that answers 403, 429 or 500 is saved as the archive, and the install ends in "Checksum error" #746 stays open narrowed to the User-Agent part (statuses fixed by fix: name the status of a refused download, hide URL credentials in messages, update via manifestUrl #747, in v1.1.0); [Feature]: Add a GitHub mirror base URL tovfox configforvfox upgrade,vfox addandvfox update#743 (mirror parameters) is untouched by these releases; [Question] vfox link command is not support by version 1.0.13 #750 is answered (upgrade to 1.1.0 forvfox link) and can be closed.The issue description is updated accordingly (§1/#337, §2 plugin bullets, §6 consumer note).
test: run a real Nushell in CI and the CLI tests on Windows (#753)