Follow-ups of #736: plugin updates, the path.mode default and vfox config

Aperta
  • Qualcosa non va?
#737 1 commento 0 reazioni 1 assegnatario Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

@linghengqian ci sta già lavorando.

Dal 22/10/2026.

  • #738 di @linghengqian — aperta
  • #739 di @linghengqian — aperta

Valutazione

Questa issue non è ancora stata valutata.

Descrizione

plan plugin

#736 is merged (feb6092). It added vfox link, vfox doctor, vfox alias, installation receipts, the optional Fingerprint and Detect hooks, PLUGIN.shadowHints and the path.mode setting. It is not released yet: main is one commit ahead of v1.0.13.

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. These stay open: #337 and #732 (solved for whoever sets path.mode baseline, for everybody only once the default changes, see 3) and #670 and #359 (aliases are in, see 1).

1. Release

  • Release vfox with #736. The plugin work below needs it.
  • Release notes: the new commands (link, doctor, alias), the path.mode setting with the advice to run vfox config path.mode baseline, and the planned change of the default (3).
  • After the release, point #337 and #732 to path.mode baseline, and decide what is left of #670 and #359. Aliases are resolved on the command line only and are never written to .vfox.toml, so the second scenario in #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.

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.

  • vfox-flutter: replace the plugin's own drift detection with a Fingerprint hook. Today lib/manifest.lua writes .vfox-manifest (the git HEAD of the SDK) from hooks/pre_install.lua, and hooks/pre_use.lua prints a warning when the HEAD has moved. The core now records the facts in the receipt, reports sdk.drift after vfox use and in vfox doctor, and vfox install --reinstall restores the version. Update docs/flutter-upgrade.md (and the zh-CN copy) to match.
  • vfox-nodejs: replace util.shadowing_node() and the Note: that hooks/pre_use.lua prints with PLUGIN.shadowHints (the pnpm explanation and the link to docs/pnpm.md). This one is more urgent than the others: with the new vfox and the current plugin, vfox use prints the core's warning and the plugin's note for the same problem.
  • vfox-java: add a Detect hook, so that vfox link --detect java finds the JDKs that are already on the machine (#706, #669). Places to look are, for example, /usr/lib/jvm and update-alternatives, /Library/Java/JavaVirtualMachines, SDKMAN, IntelliJ's ~/.jdks, Homebrew and the Windows install locations. The version names need a decision: the plugin names its own versions <java version>-<vendor> (21.0.8+9-tem), and the release file of a JDK has JAVA_VERSION and IMPLEMENTOR.
  • vfox-plugin-template: hooks/ has the seven older hooks only. Add optional fingerprint.lua and detect.lua examples and a commented PLUGIN.shadowHints in metadata.lua.
  • Where a plugin stops doing something itself (flutter's check, nodejs's PATH scan), decide between raising PLUGIN.minRuntimeVersion and keeping the old code for older vfox, which the plugin can tell from RUNTIME.version. Where it only adds a hook, no bump is needed.

Per-plugin issues can be opened in the plugin repositories and linked here. Other plugins can follow when somebody needs them, for example Detect for golang or python.

3. Change the default of path.mode to baseline

Today the default is legacy, which is the behavior of 1.0.x. Quick Start and the READMEs ask new installations to run vfox config path.mode baseline, and the configuration guide announces that it becomes the default in a future release. When to do it is a maintainer decision (in the review of #736: "That's a pretty big change! I'll take a look."). What it takes:

  • Decide the release, and whether an earlier release should warn first, for instance with a notice from vfox doctor while path.mode is not set explicitly.
  • Code: EmptyPath in internal/config/path.go, the two fallbacks in EffectiveMode (they return legacy for an empty or an unknown value; decide whether a typo should land on the new default) and the starting mode in pathPolicy() in internal/env/pathpolicy.go. A throw-away flip of these fails 11 tests in cmd/commands, internal/config, internal/env and internal/sdk, which assert the old default.
  • Docs, English and zh-hans: drop the announcements and the "set baseline" step in docs/guides/quick-start.md and both READMEs, update docs/guides/configuration.md and docs/guides/faq.md, and say how to keep the old behavior (vfox config path.mode legacy). Also the bullet in AGENTS.md that says legacy stays the default.
  • The hints of the path.shadowed finding in internal/sdk/check.go suggest vfox config path.mode baseline. Reword them.
  • Release notes: say it first, with the one-line way back.

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

vfox config <key> <value> loads the merged shared and user configuration and saves all of it into the user's config.yaml. The user's file then holds a copy of every section, the shared aliases included, and a section that the user's file declares replaces the shared one: a later change of the shared configuration no longer applies. --unset writes the default value instead of removing the key. vfox alias already edits 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.AliasFile can be generalized for this.
  • --unset removes the key, so that the shared value or the default applies again.
  • Tests: with a shared config present, setting one key copies nothing else.

5. Smaller items

  • CI has no Nushell, so the generated vfox.nu is only checked as text. Add a job that installs Nushell, sources the script and checks that vfox env sees __VFOX_ORIG_PATH. It was checked by hand with Nushell 0.116.1 for #736.
  • The CLI-level tests in cmd/commands (cliFixture in cli_test.go) skip on Windows, where only the unit tests and the E2E workflow run. Make the fixture work there, so that the junction, .cmd and PATH separator cases are covered end to end as well.

6. Open questions from the description of #736

The review did not touch these, and they get expensive to change once a release is out:

  • The names Fingerprint, Detect, shadowHints and .vfox-receipt.json.
  • Whether the warning after vfox use may be on by default (diagnostics.onUse).
  • Whether Detect belongs in the core or in the plugins.
Lingua principale
Go
Stelle
4k
Fork
167
Merge medio
2g 10h
PR unite (30g)
8

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di version-fox/vfox

Tutte le issue di version-fox/vfox

Issue simili

Altre issue su Go

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.