From 1f8a4dab499784edae9e30f2a1070d5c04b9197d Mon Sep 17 00:00:00 2001 From: Qiheng He Date: Tue, 10 Nov 2026 10:40:34 +0800 Subject: [PATCH 1/4] feat: report drift via Fingerprint hook --- docs/changes.md | 4 ++ docs/development.md | 24 ++++--- docs/flutter-upgrade.md | 130 +++++++++++++++++----------------- docs/platforms.md | 4 +- docs/troubleshooting.md | 8 +-- docs/zh-CN/changes.md | 4 ++ docs/zh-CN/development.md | 24 ++++--- docs/zh-CN/flutter-upgrade.md | 87 ++++++++++------------- docs/zh-CN/platforms.md | 2 +- docs/zh-CN/troubleshooting.md | 8 +-- hooks/fingerprint.lua | 47 ++++++++++++ hooks/pre_install.lua | 7 +- hooks/pre_use.lua | 10 +++ lib/manifest.lua | 98 +++++++++++++++++++++++++ lib/util.lua | 23 ++++++ tests/e2e/common/common.go | 10 ++- tests/e2e/linux/verify.go | 59 ++++++++------- tests/e2e/windows/verify.go | 63 +++++++++------- tests/hooks_test.lua | 108 ++++++++++++++++++++++++++++ 19 files changed, 522 insertions(+), 198 deletions(-) create mode 100644 hooks/fingerprint.lua diff --git a/docs/changes.md b/docs/changes.md index e2c12bd..a71862d 100644 --- a/docs/changes.md +++ b/docs/changes.md @@ -4,6 +4,10 @@ What changed in each release, as a user notices it. GitHub's release pages and the pull requests linked below have the rest. The newest release is 0.2.5. When `main` is ahead of it, the changes it has are listed first, under "Unreleased", and [install-from-source.md](install-from-source.md) gets you those now. +## Unreleased + +- Drift detection goes through vfox's `Fingerprint` hook (needs vfox 1.1.0 or later): the plugin reports the SDK checkout's git HEAD from files only, vfox records it in the version's receipt and reports `sdk.drift` after `vfox use` and in `vfox doctor`, fixed with `vfox install --reinstall`. The plugin no longer writes `.vfox-manifest` on new vfox and no longer prints its own warning there, so the same drift is not reported twice; vfox older than 1.1.0 keeps the old warning. See [flutter-upgrade.md](flutter-upgrade.md). + ## 0.2.5 (2026-10-21) - Installing an official release no longer asks gitcode.com ([#50](https://github.com/version-fox/vfox-flutter/pull/50)). Release 0.2.4 asked it for every install, and when gitcode.com rate-limited its API (HTTP 429) an install or a `vfox search` waited up to 6.5 minutes and printed nothing: 212 and 392 seconds on 2026-10-21. `vfox search` and the `latest` of `vfox install` still list the OpenHarmony releases, but they make two attempts, give up at HTTP 429, and print a warning on stderr when they get no list. Installing an OpenHarmony build waits as before. See [troubleshooting.md](troubleshooting.md#gitcodecom-is-rate-limited). diff --git a/docs/development.md b/docs/development.md index 05a969f..47679fc 100644 --- a/docs/development.md +++ b/docs/development.md @@ -8,13 +8,14 @@ metadata.lua plugin name, version, oldest vfox, and the note that `vfox add` prints hooks/available.lua vfox search: the list of every name hooks/pre_install.lua vfox install: resolve a name to a package; and PostInstall -hooks/pre_use.lua vfox use: warn when the SDK has drifted +hooks/pre_use.lua vfox use: the drift check for vfox older than 1.1.0 +hooks/fingerprint.lua vfox use / doctor on vfox 1.1.0+: the git HEAD fact hooks/env_keys.lua PATH -lib/util.lua the mirror, the platform, version names and their order +lib/util.lua the mirror, the platform, version names, their order, and the vfox version gate lib/git.lua git commands, the GitHub mirror, the work directory lib/source.lua source installs on Linux ARM64 and Windows ARM64 lib/ohos.lua OpenHarmony releases and checkouts -lib/manifest.lua .vfox-manifest and the pubspec.lock fix +lib/manifest.lua the Fingerprint HEAD reader, the legacy `.vfox-manifest`, and the pubspec.lock fix tests/hooks_test.lua offline hook tests tests/e2e/ container tests, see e2e.md Injection.lua type hints for what vfox injects, never loaded @@ -30,8 +31,8 @@ vfox loads `metadata.lua`, calls a hook when a command needs it, and puts `PLUGI | You run | Hooks | | --- | --- | | `vfox search flutter` | `Available` | -| `vfox install flutter@3.47.4` | `PreInstall` returns the package, and calls `Available` itself to find it. vfox downloads, verifies and unpacks, then calls `PostInstall` | -| `vfox use flutter@3.47.4` | `PreUse` checks the SDK and returns the name. `EnvKeys` provides `PATH` | +| `vfox install flutter@3.47.4` | `PreInstall` returns the package, and calls `Available` itself to find it. vfox downloads, verifies and unpacks, then calls `PostInstall`. vfox 1.1.0+ records the `Fingerprint` fact in the receipt then | +| `vfox use flutter@3.47.4` | vfox 1.1.0+ compares the `Fingerprint` fact and reports `sdk.drift`. Older vfox runs `PreUse`, which checks the SDK and returns the name. `EnvKeys` provides `PATH` | | `vfox uninstall flutter@3.47.4` | none, the name has to be exact | ## Contracts that cost time @@ -41,10 +42,11 @@ vfox loads `metadata.lua`, calls a hook when a command needs it, and puts `PLUGI - `PreInstall` calls `self:Available({ officialOnly = true })` and so does not use vfox's 12-hour cache of the list. Every install reads the index. `officialOnly` leaves out the OpenHarmony releases: an official install has no use for them, and gitcode.com rate-limits the API they come from. vfox calls `Available` with its own context (`vfox search`, and the `latest` of `vfox install`), and those lists have them. - `PreInstall` returns `nil` for a name it cannot resolve, which vfox reports as `no installable runtime provided`. It raises an error for a failure: the message of `error()` shows up in the `plugin [PreInstall] method error:` line. - The index lists some releases more than once. `newestPublications` in `hooks/available.lua` keeps the newest entry (`release_date`) of each archive of a version, because a file that was uploaded again has the checksum of the newest entry only (see [troubleshooting.md](troubleshooting.md#checksum-error)). Different versions never merge, and a release in two channels has an archive in each and keeps both. `table.sort` is not stable, so the comparator has to tell any two entries apart, or equal entries come out in an order that depends on the whole input, and `PreInstall` takes the first match. It ends with the version and the channel for that. -- `PostInstall` reads `ctx.sdkInfo[PLUGIN.name]`. It runs the manifest and the `pubspec.lock` fix under `pcall`, so a failure there never fails the install. +- `PostInstall` reads `ctx.sdkInfo[PLUGIN.name]`. It runs the `pubspec.lock` fix under `pcall`, so a failure there never fails the install. The legacy `.vfox-manifest` is only written when the running vfox is older than 1.1.0 (`supportsFingerprint` in `lib/util.lua`): newer vfox records the `Fingerprint` fact in the version's receipt instead. +- `Fingerprint` reports the commit the SDK checkout is at as `facts.head`, by reading `.git/HEAD` (and the ref or `packed-refs` it points to) from files only: no processes, no network, well under the 50 ms the hook must keep. It returns nil when there is nothing to check (no `.git`), and vfox stays silent then. Archive installs, source installs and OpenHarmony builds all report it. `PreUse` skips its own drift check on vfox 1.1.0+ (`supportsFingerprint(ctx.runtimeVersion)`) so the same drift is not reported twice; older vfox keeps the plugin's own warning from `.vfox-manifest`. - vfox unpacks a `.tar.xz` with Go's `archive/tar`, which stamps files with the time of the extraction and not with the time stored in the archive. The official `tar -xf` flow keeps those times, and `packages/flutter_tools/pubspec.lock` is newer than `pubspec.yaml` after it. After a vfox install the two share the time of the extraction, and whichever is written last looks newer, so `bin/internal/shared.sh` can find `pubspec.yaml` newer than `pubspec.lock` and rebuild the tool on the first run (`Building flutter tool...`). `manifest.touchPubspecLock` rewrites `pubspec.lock`, on every platform, to restore the order ([#37](https://github.com/version-fox/vfox-flutter/issues/37)). Source installs build the tool on the first run by design. - A Windows command line reaches `cmd.exe` as vfox 1.0.13 and later write it, unchanged ([vfox#712](https://github.com/version-fox/vfox/pull/712)), and older versions quote it again. `quote` in `lib/git.lua` and `lib/manifest.lua` puts double quotes around a path that contains whitespace, and leaves other paths bare, so that a path with a space works on 1.0.13 and a path without one still works on older versions. -- `os.execute` reports success as `0` or as `true`, depending on the Lua it runs in, and `exec` in `lib/git.lua` accepts both. `io.popen` is how the plugin reads the output of `git`; a command that prints nothing or fails reads as `nil`, which is why a missing `git` goes unnoticed in `lib/manifest.lua`. +- `os.execute` reports success as `0` or as `true`, depending on the Lua it runs in, and `exec` in `lib/git.lua` accepts both. `io.popen` is how the plugin reads the output of `git` outside `Fingerprint` (the legacy drift check, the `git` commands of source installs); a command that prints nothing or fails reads as `nil`, which is why a missing `git` goes unnoticed in `lib/manifest.lua`. `Fingerprint` itself never uses `io.popen` or `os.execute`. - `lib/git.lua` takes the work directory from `VFOX_HOME`, then `HOME`, then `USERPROFILE`, and appends `.vfox/tmp/`. With `VFOX_HOME` set that is `$VFOX_HOME/.vfox/tmp/`, one `.vfox` below the vfox home. The directory is not removed when the install fails. - `git` runs with your configuration, except for two settings that `git.init` writes into the checkout: `core.longpaths=true`, and `core.autocrlf=false`, because a global `true` writes Flutter's shell scripts with CRLF (see [arm64.md](arm64.md#limits)). On Windows `false` writes the same CRLF files `true` does, since `core.eol` is native there. That is how git works, and it was checked on Linux with `core.eol=crlf` and Flutter's `.gitattributes`, which starts with `* text=auto`: the same files came out CRLF for both settings, and `bin/flutter` stayed LF. The Windows ARM64 container tests install from a checkout like this one. Fetches get `http.lowSpeedLimit=1000` and `http.lowSpeedTime=60`, which `GIT_HTTP_LOW_SPEED_LIMIT` and `GIT_HTTP_LOW_SPEED_TIME` override. - `lib/ohos.lua` waits for gitcode.com in two ways. Installing a build needs the releases, and makes five attempts: 10 seconds apart, and 30, 60, 120 and 180 seconds after HTTP 429. Listing them is a courtesy to `vfox search`, so `ohos.list()` makes two attempts 2 seconds apart, stops at HTTP 429, and returns `nil` and the reason. `Available` then writes one warning line to stderr and lists the official releases. @@ -106,7 +108,7 @@ Run it from the repository root. The test stubs `http`, `json` and `os.getenv`, - a checkout does not take `core.autocrlf` from your git configuration (this one runs real `git`, and skips itself without it); - an unsupported CPU is named in the message. -The manifest and `PreUse` are not in this file, and source installs and OpenHarmony builds only up to their `git` commands. The container tests cover them, see [e2e.md](e2e.md). Lint, license headers and the container tests are in [e2e.md](e2e.md#local-checks). +The `Fingerprint` file reader and the `PreUse` version gate are not in this file either. The container tests cover the drift end to end, see [e2e.md](e2e.md). Lint, license headers and the container tests are in [e2e.md](e2e.md#local-checks). To call a single hook, vfox 1.0.13 and later has `vfox plugin run`. It does not register the plugin, and `--os` and `--arch` answer for another platform: @@ -119,7 +121,7 @@ Both ask the real index and gitcode.com. A source install (`--os linux --arch ar ### Trying a change without downloading gigabytes -An archive is 1.6 to 2.3 GB, so a change to the resolution is cheaper to try against a fake mirror: a copy of the real index whose archives are one tiny SDK. The SDK holds a `flutter/bin/flutter` script and a real git repository, so the manifest and the drift check run for real. Run it on Linux, from the root of the repository. It sets `HOME` and `VFOX_HOME` to a scratch directory, which vfox needs both of, so your real vfox is left alone. +An archive is 1.6 to 2.3 GB, so a change to the resolution is cheaper to try against a fake mirror: a copy of the real index whose archives are one tiny SDK. The SDK holds a `flutter/bin/flutter` script and a real git repository, so the receipt and the drift check run for real. Run it on Linux, from the root of the repository. It sets `HOME` and `VFOX_HOME` to a scratch directory, which vfox needs both of, so your real vfox is left alone. ```bash work=$(mktemp -d) @@ -202,7 +204,7 @@ The Linux row of the table is where the script starts to ask (storage has the SD - **A new way to name or choose.** Change `hooks/available.lua` (the order) or `hooks/pre_install.lua` (the choice), add a case to `tests/hooks_test.lua`, and update [versions.md](versions.md), [channels.md](channels.md) and [arm64.md](arm64.md) where they describe it. - **A new platform.** `getOsTypeAndArch` in `lib/util.lua` lists the CPUs. A platform that installs from git adds itself to `SOURCE_INSTALL_PLATFORMS` and `OLDEST_NATIVE` in `lib/source.lua`. Update [platforms.md](platforms.md) and the tables in [arm64.md](arm64.md), and add it to the container tests if a runner exists ([e2e.md](e2e.md)). - **A new source of builds** like OpenHarmony: a module in `lib/` that lists names and checks them out, a branch in `Available`, `PreInstall` and `PostInstall`, a flavor in `tests/e2e/common/common.go` (`DefaultFlavours`, `DefaultOhosVersion`), and a page in `docs/`. -- **A message.** The container tests assert parts of the drift warning (`tests/e2e/linux/verify.go` and `tests/e2e/windows/verify.go`). Change the Lua and both files together, and the text in [flutter-upgrade.md](flutter-upgrade.md). +- **A message.** The container tests assert the core's drift report (`tests/e2e/linux/verify.go` and `tests/e2e/windows/verify.go`). Change the Lua and both files together, and the text in [flutter-upgrade.md](flutter-upgrade.md). ## Known gaps @@ -216,7 +218,7 @@ The Linux row of the table is where the script starts to ask (storage has the SD ## Releasing -A maintainer runs **Actions → Plugin → Run workflow** on the default branch with the version, without `v`. The [README](../README.md#releasing-this-plugin) describes what the shared workflow does. Afterwards `plugins/flutter.json` in [vfox-plugins](https://github.com/version-fox/vfox-plugins) shows the version that `vfox add flutter` serves. That lags the release by hours: 1 h 22 min for 0.2.2, 4 h for 0.2.3 and 2 h 28 min for 0.2.4. Then bring the docs up to date, in both languages: move the "Unreleased" entries of [changes.md](changes.md) under the new version, dated with the day of the release, name that version as the newest one in its first paragraph, put it in the `plugin_version` of the manifest in [flutter-upgrade.md](flutter-upgrade.md#how-the-check-works), and take the "Unreleased" marks out of the other pages, see [Writing the docs](#writing-the-docs). +A maintainer runs **Actions → Plugin → Run workflow** on the default branch with the version, without `v`. The [README](../README.md#releasing-this-plugin) describes what the shared workflow does. Afterwards `plugins/flutter.json` in [vfox-plugins](https://github.com/version-fox/vfox-plugins) shows the version that `vfox add flutter` serves. That lags the release by hours: 1 h 22 min for 0.2.2, 4 h for 0.2.3 and 2 h 28 min for 0.2.4. Then bring the docs up to date, in both languages: move the "Unreleased" entries of [changes.md](changes.md) under the new version, dated with the day of the release, name that version as the newest one in its first paragraph, and take the "Unreleased" marks out of the other pages, see [Writing the docs](#writing-the-docs). ## Writing the docs diff --git a/docs/flutter-upgrade.md b/docs/flutter-upgrade.md index ca908c6..72df194 100644 --- a/docs/flutter-upgrade.md +++ b/docs/flutter-upgrade.md @@ -23,99 +23,99 @@ too, and the same goes for them. ## Recovering a drifted SDK -If you already upgraded in place, this plugin prints a warning on every -`vfox use` of that version and shows the commands that restore it: +If you already upgraded in place, restore the version with: ```bash -vfox uninstall flutter@3.47.0 -vfox install flutter@3.47.0 -vfox use flutter@3.47.0 +vfox install --reinstall flutter@3.47.0 ``` +`vfox doctor` reports the same finding (`sdk.drift`), and a linked SDK that +changed reports it as a notice only: vfox does not own that SDK. + ## The warning -This is what `vfox use flutter@3.47.4` prints once the SDK's HEAD is not the commit vfox -installed: +This needs vfox 1.1.0 or later, which records the installation and compares it +again on every `vfox use`. This is what `vfox use flutter@3.47.4` prints once +the SDK's HEAD is not the commit vfox installed: ``` -Warning: flutter SDK at ~/.vfox/cache/flutter/v-3.47.4 has drifted from the version vfox installed. - vfox installed: flutter@3.47.4 (git HEAD 9584c6713b324636289d067944a46fd6b49df14b) - current git HEAD: abaf9c523780a608bd46686fd5e53740a07077f8 - reason: the SDK's git HEAD no longer matches the commit vfox installed - -This typically happens when `flutter upgrade` or a similar in-place command -is run inside a vfox-managed SDK. vfox manages SDK versions by directory and -does not track in-place mutations, so the version you get may differ from -the one you asked for. - -To restore flutter@3.47.4: - vfox uninstall flutter@3.47.4 - vfox install flutter@3.47.4 - vfox use flutter@3.47.4 - -To upgrade to a newer version, use vfox directly: - vfox install flutter@ - vfox use flutter@ +flutter@3.47.4 has changed since vfox installed it (head: 9584c6713b32… -> abaf9c523780…). + Something modified the SDK in place, for example a self-update command. vfox manages versions by directory and does not track that. + To move to a newer version, install it with vfox instead: vfox install flutter@ + Fix: vfox install --reinstall flutter@3.47.4 ``` -There are two reasons, and the line after `reason:` says which: +The `head:` part names the recorded commit first and the current one second, +both shortened. When the current HEAD cannot be read at all (its `.git` is +damaged), it reads `unreadable` instead of a commit. -| Reason | Meaning | -| --- | --- | -| `the SDK's git HEAD no longer matches the commit vfox installed` | The commit changed. This is what `flutter upgrade`, `flutter downgrade`, `flutter channel` and `git checkout` do | -| `vfox can no longer read the SDK's git HEAD (its .git may be broken)` | `git` fails in the SDK: the `.git` directory is damaged, or `git` is not installed any more | +The warning is only a warning: `vfox use` still selects the version you asked +for, and exits with 0. SDKs without a `.git` directory are left alone. -The path in the first line is the directory that `vfox info flutter@3.47.4` prints. The -SDK is the `flutter-3.47.4` directory inside it. +With vfox older than 1.1.0 the plugin prints its own warning instead (it never +loads the `Fingerprint` hook), with the commands that reinstall the version by +hand. Update vfox to get the check above. ## How the check works -On install the plugin writes a `.vfox-manifest` file next to the SDK's `.git`, -recording the expected git HEAD, and re-checks it on each `vfox use`. - -The manifest is a small JSON file in the root of the SDK, `flutter-3.47.4/.vfox-manifest`: +On install and on `vfox link` the plugin reports the commit the SDK checkout +is at through its `Fingerprint` hook, by reading `.git/HEAD` (and the ref or +`packed-refs` it points to) from files only. vfox keeps that fact in the +version's receipt, `.vfox-receipt.json` in the directory that +`vfox info flutter@3.47.4` prints: ```json -{"expected_head":"9584c6713b324636289d067944a46fd6b49df14b","installed_at":1792523751,"plugin":"vfox-flutter","plugin_version":"0.2.5","version":"3.47.4"} +{ + "schema": 1, + "sdk": "flutter", + "version": "3.47.4", + "origin": "installed", + "facts": { + "head": "9584c6713b324636289d067944a46fd6b49df14b" + } +} ``` -`expected_head` is what `git rev-parse HEAD` printed right after vfox unpacked the SDK, and -`installed_at` is the time of the install in seconds since 1970. The check runs -`git rev-parse HEAD` again on `vfox use` and compares the two. Archive installs, source -installs and OpenHarmony builds all get a manifest. `git status` in the SDK lists the file -as untracked. +`vfox use` and `vfox doctor` report `sdk.drift` when the fact is no longer the +same. Archive installs, source installs and OpenHarmony builds all report it. +A fact the plugin can no longer read counts as a change too. -The warning is only a warning: `vfox use` still selects the version you asked -for, and exits with 0. SDKs without a `.git` directory are left alone. +Nothing is checked when there is nothing to compare with: an SDK without a +fact (one installed where there was no `.git` to read), a version installed +before vfox kept receipts (see `vfox doctor --adopt` below), and a version +vfox does not know are all silent. -Nothing is checked when there is nothing to compare with: an SDK without a manifest (one -installed by a plugin older than 0.2.3), a manifest without `expected_head` (the install -ran where `git` was missing), and a version vfox does not know are all silent. +Versions installed by a plugin older than this one may still carry a +`.vfox-manifest` file in the SDK root (`flutter-3.47.0/.vfox-manifest`). The +current plugin neither writes nor reads it; it is ignored and can be deleted. +It shows as untracked in the SDK's `git status` while it is there. -## Disabling the check +A version installed before vfox kept receipts has no receipt to compare with. +`vfox doctor` says so (`sdk.no-receipt`), and takes the current state as the +baseline on request: -Delete the `.vfox-manifest` file of the affected installation. The file is -written by a real install, so it comes back only after you uninstall and -reinstall that version; `vfox install` alone skips an already-installed -version and leaves it absent. - -`vfox info --format '{{.Path}}' flutter@3.47.0` prints the directory above the SDK, so the -manifest is one level further down, in `flutter-3.47.0`. The directory is named after the -installed name, which carries an architecture suffix if you installed with one -(`flutter-3.47.0-x64`). +```bash +vfox doctor --adopt flutter@3.47.0 +``` -### Ubuntu 26.04.1 +## Disabling the check -Execute in Bash, +The check is one of the fast checks `vfox use` runs after it selects a version. +To stop running them: ```bash -rm "$(vfox info --format '{{.Path}}' flutter@3.47.0)/flutter-3.47.0/.vfox-manifest" +vfox config diagnostics.onUse false ``` -### Windows 11 - -Assume that PowerShell 7 is already installed. Execute in PowerShell 7, +To silence only this finding for one version, add it to `diagnostics.ignore` in +your `config.yaml`: -```powershell -Remove-Item "$(vfox info --format '{{.Path}}' flutter@3.47.0)/flutter-3.47.0/.vfox-manifest" +```yaml +diagnostics: + ignore: + - "sdk.drift:flutter@3.47.0" ``` + +See vfox's [configuration](https://vfox.dev/guides/configuration.html#diagnostics-settings) +and [`vfox doctor`](https://vfox.dev/usage/core-commands.html#doctor) for the +rest of the findings. diff --git a/docs/platforms.md b/docs/platforms.md index 0f76589..8c7798d 100644 --- a/docs/platforms.md +++ b/docs/platforms.md @@ -20,7 +20,7 @@ What each machine gets for `3.47.4`, `3.47.4-x64` and `3.47.4-arm64` is in [arm6 ## Requirements - **vfox**, hooked into your shell, so that `flutter` is on the `PATH` after `vfox use`, see vfox's [quick start](https://vfox.dev/guides/quick-start.html). The plugin declares vfox 0.3.0 as the oldest it loads on. The tests run against the latest vfox release and against vfox's `main`, and a Windows account whose home directory contains a space needs vfox 1.0.13 or later ([vfox#712](https://github.com/version-fox/vfox/pull/712)). -- **`git`**, for Linux ARM64 and Windows ARM64 (every install), for OpenHarmony builds, and for the drift check of [flutter-upgrade.md](flutter-upgrade.md). That check asks `git` for the SDK's commit when it installs; without `git` the install still succeeds, writes a `.vfox-manifest` that has no commit, and `vfox use` never warns. Flutter itself needs `git` as well. +- **`git`**, for Linux ARM64 and Windows ARM64 (every install) and for OpenHarmony builds. The drift check of [flutter-upgrade.md](flutter-upgrade.md) reads the SDK's `.git/HEAD` from files only and needs no `git` binary: an SDK without a `.git` to read simply has no fact to compare. Flutter itself needs `git` as well. - **Flutter's own tools.** Android, iOS, Linux, Windows and web development have requirements of their own (Android SDK, Xcode, Visual Studio, GTK and more). vfox does not install them, see [Flutter's installation guide](https://docs.flutter.dev/install). The example in the [README](../README.md#install) installs `curl git unzip xz-utils zip libglu1-mesa` for Ubuntu. - **Disk space.** An archive is 1.6 to 2.3 GB (see [versions.md](versions.md#installing)), and vfox removes it after unpacking. The SDK grows as the `flutter` tool downloads what it needs for the platforms you build for. A source install needs room for the checkout as well. Every name you install is a separate SDK, see [versions.md](versions.md#installed-names). @@ -45,6 +45,6 @@ The container suites install a real Flutter with real vfox, in a throwaway conta | Linux x64 and Linux ARM64 | Ubuntu 26.04, driven from bash. A second test uses zsh and a Homebrew vfox | 3.47.4 | the latest release and `main` | | Windows x64 and Windows ARM64 | Windows Server 2025 Server Core, driven from PowerShell 7, with a vfox home in a path that contains a space | 3.47.4 | the latest release and `main` | -On x64 the runs repeat for the OpenHarmony build 3.41.10-ohos-1.0.0, and, with the latest vfox only, with the CFUG mirror set. ARM64 runs the official build only. Each run installs the version, checks the drift warning, and boots `flutter` and `dart`. +On x64 the runs repeat for the OpenHarmony build 3.41.10-ohos-1.0.0, and, with the latest vfox only, with the CFUG mirror set. ARM64 runs the official build only. Each run installs the version, checks the `sdk.drift` report, and boots `flutter` and `dart`. macOS is not in the container suites, because a container cannot run it. Its architecture selection is covered by the offline tests only. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 704e1e0..a86c39f 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -28,7 +28,7 @@ The plugin found nothing for the name you typed. The usual reasons: ### `flutter@3.47.4 is already installed` -The name is installed. vfox does not download again, and does not write the `.vfox-manifest` again, see [flutter-upgrade.md](flutter-upgrade.md#disabling-the-check). +The name is installed. vfox does not download again. To replace it with a fresh copy, for example after `flutter upgrade` moved it in place, run `vfox install --reinstall flutter@3.47.4`, see [flutter-upgrade.md](flutter-upgrade.md#recovering-a-drifted-sdk). ### `get version failed: ... (status ...)` @@ -59,9 +59,9 @@ vfox downloaded the archive and its SHA-256 differs from the one in Flutter's re The plugin lists only the newest entry of such a file, so these three install. Releases before 0.2.5 list every entry and install the one that sorts first. In release 0.2.4 that is arbitrary for entries that are equal, and it also depends on the rest of the list, such as how many OpenHarmony releases it holds. On 2026-10-21 it took an old entry for all three on Linux x64, and for some of them on macOS and Windows, and the install ended as above. Update the plugin, or install a release next to it (`3.13.2` or `3.13.4` instead of `3.13.3`). There is no switch to skip the check. -### `Warning: flutter SDK at ... has drifted from the version vfox installed.` +### `flutter@3.47.4 has changed since vfox installed it` -`flutter upgrade`, `flutter channel` or a `git` command moved the SDK. `vfox use` still selects it. See [flutter-upgrade.md](flutter-upgrade.md). +`flutter upgrade`, `flutter channel` or a `git` command moved the SDK. `vfox use` still selects it. Restore it with `vfox install --reinstall flutter@3.47.4`. See [flutter-upgrade.md](flutter-upgrade.md). ### `flutter does not support the 386 architecture` @@ -170,7 +170,7 @@ Minutes later the same API answered in a second. Without a 429 a failing request - **Flutter says "A new version of Flutter is available!" and suggests `flutter upgrade`.** Ignore it: `flutter upgrade` moves the SDK under vfox, see [flutter-upgrade.md](flutter-upgrade.md). `vfox install flutter@stable` is the upgrade. `flutter --no-version-check` leaves the banner out. - **`FLUTTER_ROOT` is not set.** The plugin sets only `PATH`. The `flutter` script finds its own directory. - **`dart` is there without a Dart plugin.** The Flutter SDK includes the Dart SDK, and `dart` is in its `bin`. There is no need to add the [vfox-dart](https://github.com/version-fox/vfox-dart) plugin next to it. -- **`.vfox-manifest` is untracked in the SDK's git.** The plugin writes it, see [flutter-upgrade.md](flutter-upgrade.md). +- **`.vfox-manifest` is untracked in the SDK's git.** Releases of this plugin before the `Fingerprint` hook wrote it; the current plugin neither writes nor reads it, and it can be deleted. See [flutter-upgrade.md](flutter-upgrade.md#how-the-check-works). - **`flutter pub get` is slow or fails in China.** Packages come from `PUB_HOSTED_URL`, which the plugin does not touch, see [mirror.md](mirror.md#which-installs-use-which-mirror). - **The first `flutter` command downloads a lot.** The Flutter tool fetches what it needs the first time you build for a platform, and it reads `FLUTTER_STORAGE_BASE_URL` for it, so keep the mirror variable set, see [mirror.md](mirror.md#what-the-variable-does). diff --git a/docs/zh-CN/changes.md b/docs/zh-CN/changes.md index d687d71..9cb69ce 100644 --- a/docs/zh-CN/changes.md +++ b/docs/zh-CN/changes.md @@ -4,6 +4,10 @@ 每个版本改了什么,写成用户能感受到的样子。其余的细节见 GitHub 的发布页面和下面链接的 pull request。最新的发布版是 0.2.5。`main` 领先于它时,多出来的改动列在最前面的“未发布”下,想现在就用上它们,见 [install-from-source.md](install-from-source.md)。 +## 未发布 + +- 漂移检查走 vfox 的 `Fingerprint` 钩子(需要 vfox 1.1.0 或更新的版本):插件只从文件读取 SDK 检出的 git HEAD 并报告,vfox 把它记在版本的收据里,`vfox use` 之后和 `vfox doctor` 里报告 `sdk.drift`,用 `vfox install --reinstall` 恢复。新版 vfox 上插件不再写 `.vfox-manifest`,也不再打印自己的警告,以免同一处漂移报两次;老于 1.1.0 的 vfox 保留旧的警告。见 [flutter-upgrade.md](flutter-upgrade.md)。 + ## 0.2.5 (2026-10-21) - 安装官方版本不再访问 gitcode.com([#50](https://github.com/version-fox/vfox-flutter/pull/50))。0.2.4 每次安装都要问它,而 gitcode.com 对它的 API 限流(HTTP 429)时,一次安装或一次 `vfox search` 最多会等 6.5 分钟,什么也不打印:2026-10-21 测得 212 秒和 392 秒。`vfox search` 和 `vfox install` 的 `latest` 仍然会列出 OpenHarmony 的发布版本,但它们只尝试两次,遇到 HTTP 429 就放弃,拿不到列表时在 stderr 上打印一条警告。安装 OpenHarmony 构建版本还是和以前一样会等。见 [troubleshooting.md](troubleshooting.md#gitcodecom-被限流)。 diff --git a/docs/zh-CN/development.md b/docs/zh-CN/development.md index 56b4834..e1f1bc4 100644 --- a/docs/zh-CN/development.md +++ b/docs/zh-CN/development.md @@ -8,13 +8,14 @@ metadata.lua 插件名、版本、最老的 vfox,以及 `vfox add` 打印的提示 hooks/available.lua vfox search:所有名字的列表 hooks/pre_install.lua vfox install:把名字解析成一个包;还有 PostInstall -hooks/pre_use.lua vfox use:SDK 漂移时给出警告 +hooks/pre_use.lua vfox use:vfox 老于 1.1.0 时的漂移检查 +hooks/fingerprint.lua vfox 1.1.0 及更新的版本上,`vfox use` / `doctor` 用的 git HEAD 事实 hooks/env_keys.lua PATH -lib/util.lua 镜像、平台、版本名及其顺序 +lib/util.lua 镜像、平台、版本名及其顺序,还有 vfox 版本的判断 lib/git.lua git 命令、GitHub 镜像、工作目录 lib/source.lua Linux ARM64 和 Windows ARM64 的源码安装 lib/ohos.lua OpenHarmony 发布版本和检出 -lib/manifest.lua .vfox-manifest 和 pubspec.lock 的修正 +lib/manifest.lua Fingerprint 的 HEAD 读取、旧的 `.vfox-manifest`,以及 pubspec.lock 的修正 tests/hooks_test.lua 离线的 hook 测试 tests/e2e/ 容器测试,见 e2e.md Injection.lua vfox 注入内容的类型提示,从不加载 @@ -30,8 +31,8 @@ vfox 加载 `metadata.lua`,在命令需要时调用 hook,并把 `PLUGIN` 和 | 你执行 | 用到的 hook | | --- | --- | | `vfox search flutter` | `Available` | -| `vfox install flutter@3.47.4` | `PreInstall` 返回包,并自己调用 `Available` 来找它。vfox 下载、验证并解压,然后调用 `PostInstall` | -| `vfox use flutter@3.47.4` | `PreUse` 检查 SDK 并返回名字。`EnvKeys` 提供 `PATH` | +| `vfox install flutter@3.47.4` | `PreInstall` 返回包,并自己调用 `Available` 来找它。vfox 下载、验证并解压,然后调用 `PostInstall`。vfox 1.1.0 及更新的版本随后把 `Fingerprint` 事实记进收据 | +| `vfox use flutter@3.47.4` | vfox 1.1.0 及更新的版本比对 `Fingerprint` 事实并报告 `sdk.drift`。更老的 vfox 运行 `PreUse`,它检查 SDK 并返回名字。`EnvKeys` 提供 `PATH` | | `vfox uninstall flutter@3.47.4` | 没有,名字必须准确 | ## 容易踩坑的约定 @@ -41,10 +42,11 @@ vfox 加载 `metadata.lua`,在命令需要时调用 hook,并把 `PLUGIN` 和 - `PreInstall` 调用的是 `self:Available({ officialOnly = true })`,所以用不到 vfox 对列表的 12 小时缓存。每次安装都要读索引。`officialOnly` 会略去 OpenHarmony 发布版本:官方版本的安装用不着它们,而且它们来自的 API 被 gitcode.com 限流。vfox 用它自己的上下文调用 `Available`(`vfox search`,以及 `vfox install` 的 `latest`),那样的列表里有它们。 - `PreInstall` 对解析不了的名字返回 `nil`,vfox 会把它报告成 `no installable runtime provided`。失败时它会抛出错误:`error()` 的内容会出现在 `plugin [PreInstall] method error:` 那一行里。 - 索引里有些版本不止列了一次。`hooks/available.lua` 里的 `newestPublications` 对一个版本的每个压缩包只保留最新(`release_date`)的那条,因为重新上传过的文件,只有最新那条的校验和才是对的(见 [troubleshooting.md](troubleshooting.md#checksum-error))。不同的版本绝不会合并,在两个渠道里的版本各有一个压缩包,两条都保留。`table.sort` 不是稳定排序,所以比较函数必须能区分任意两个条目,否则相等的条目出来的顺序取决于整个输入,而 `PreInstall` 取第一个匹配的。为此比较函数最后还比较版本和渠道。 -- `PostInstall` 读取 `ctx.sdkInfo[PLUGIN.name]`。清单和 `pubspec.lock` 的修正都在 `pcall` 里运行,所以那里的失败永远不会让安装失败。 +- `PostInstall` 读取 `ctx.sdkInfo[PLUGIN.name]`。`pubspec.lock` 的修正放在 `pcall` 里,所以那里的失败永远不会让安装失败。旧的 `.vfox-manifest` 只在运行的 vfox 老于 1.1.0 时才写(`lib/util.lua` 里的 `supportsFingerprint`):新版 vfox 把 `Fingerprint` 事实记在版本的收据里。 +- `Fingerprint` 把 SDK 检出所在的提交作为 `facts.head` 报告,只从文件读 `.git/HEAD`(以及它指向的 ref 或 `packed-refs`):不跑进程,不访问网络,远快于 hook 要求的 50 毫秒。没有可检查的东西(没有 `.git`)时返回 nil,vfox 就保持安静。压缩包安装、源码安装和 OpenHarmony 构建版本都会报告。`PreUse` 在 vfox 1.1.0 及更新的版本上跳过自己的漂移检查(`supportsFingerprint(ctx.runtimeVersion)`),以免同一处漂移报两次;更老的 vfox 保留插件自己的 `.vfox-manifest` 警告。 - vfox 用 Go 的 `archive/tar` 解压 `.tar.xz`,它给文件打上的是解压时的时间,而不是压缩包里存的时间。官方的 `tar -xf` 流程会保留那些时间,于是 `packages/flutter_tools/pubspec.lock` 比 `pubspec.yaml` 新。vfox 安装之后,两者共用解压的时间,谁最后写入谁就显得更新,所以 `bin/internal/shared.sh` 可能发现 `pubspec.yaml` 比 `pubspec.lock` 新,在第一次运行时重新构建工具(`Building flutter tool...`)。`manifest.touchPubspecLock` 在所有平台上重写 `pubspec.lock`,把顺序恢复过来([#37](https://github.com/version-fox/vfox-flutter/issues/37))。源码安装按设计就要在第一次运行时构建工具。 - Windows 上的命令行,在 vfox 1.0.13 及更新的版本里原样交给 `cmd.exe`([vfox#712](https://github.com/version-fox/vfox/pull/712)),更老的版本会再加一层引号。`lib/git.lua` 和 `lib/manifest.lua` 里的 `quote` 只给含有空白字符的路径加双引号,其他路径保持原样,这样带空格的路径在 1.0.13 上可用,不带空格的路径在更老的版本上也依然可用。 -- `os.execute` 报告成功的方式,视所用的 Lua 而定,可能是 `0`,也可能是 `true`,`lib/git.lua` 里的 `exec` 两者都接受。插件读取 `git` 的输出靠的是 `io.popen`;没有输出或失败的命令读出来是 `nil`,所以 `lib/manifest.lua` 里缺少 `git` 时不会有任何察觉。 +- `os.execute` 报告成功的方式,视所用的 Lua 而定,可能是 `0`,也可能是 `true`,`lib/git.lua` 里的 `exec` 两者都接受。插件在 `Fingerprint` 之外读取 `git` 的输出靠的是 `io.popen`(旧的漂移检查、源码安装的 `git` 命令);没有输出或失败的命令读出来是 `nil`,所以 `lib/manifest.lua` 里缺少 `git` 时不会有任何察觉。`Fingerprint` 本身从不用 `io.popen` 或 `os.execute`。 - `lib/git.lua` 的工作目录依次取自 `VFOX_HOME`、`HOME`、`USERPROFILE`,再加上 `.vfox/tmp/<名称>`。设置了 `VFOX_HOME` 时就是 `$VFOX_HOME/.vfox/tmp/<名称>`,比 vfox 主目录低一层 `.vfox`。安装失败时这个目录不会被删除。 - `git` 用的是你的配置,只有 `git.init` 写进检出里的两项设置例外:`core.longpaths=true`,以及 `core.autocrlf=false`,因为全局的 `true` 会让 Flutter 的 shell 脚本带上 CRLF(见 [arm64.md](arm64.md#限制))。在 Windows 上 `false` 写出的 CRLF 文件和 `true` 一样,因为那里的 `core.eol` 是 native。这是 git 本身的工作方式,我们在 Linux 上用 `core.eol=crlf` 和 Flutter 的 `.gitattributes`(第一条是 `* text=auto`)检查过:两种设置写出的文件同样是 CRLF,`bin/flutter` 则保持 LF。Windows ARM64 的容器测试装的就是这样的检出。拉取时会加上 `http.lowSpeedLimit=1000` 和 `http.lowSpeedTime=60`,`GIT_HTTP_LOW_SPEED_LIMIT` 和 `GIT_HTTP_LOW_SPEED_TIME` 可以覆盖它们。 - `lib/ohos.lua` 等 gitcode.com 有两种方式。安装构建版本需要发布版本列表,所以尝试五次:间隔 10 秒,遇到 HTTP 429 之后是 30、60、120 和 180 秒。列出它们只是给 `vfox search` 帮个忙,所以 `ohos.list()` 只尝试两次,间隔 2 秒,遇到 HTTP 429 就停,并返回 `nil` 和原因。然后 `Available` 往 stderr 写一行警告,再列出官方版本。 @@ -106,7 +108,7 @@ go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/hooks_test.lua - 检出不会采用你 git 配置里的 `core.autocrlf`(这一项运行真正的 `git`,没有它就跳过); - 不支持的 CPU 会在提示里点出名字。 -清单和 `PreUse` 不在这个文件里,源码安装和 OpenHarmony 构建版本也只测到它们的 `git` 命令为止。这些由容器测试覆盖,见 [e2e.md](e2e.md)。lint、许可证头和容器测试见 [e2e.md](e2e.md#本地检查)。 +`Fingerprint` 的文件读取和 `PreUse` 的版本判断不在这个文件里,源码安装和 OpenHarmony 构建版本也只测到它们的 `git` 命令为止。这些由容器测试覆盖,见 [e2e.md](e2e.md)。lint、许可证头和容器测试见 [e2e.md](e2e.md#本地检查)。 要单独调用一个 hook,vfox 1.0.13 及更新的版本有 `vfox plugin run`。它不会注册插件,`--os` 和 `--arch` 可以替另一个平台作答: @@ -119,7 +121,7 @@ vfox plugin run . PreInstall --input '{"version":"stable"}' --os darwin --arch a ### 不下载几个 GB 就试验改动 -一个压缩包有 1.6 到 2.3 GB,所以试验解析方面的改动,用一个假镜像更省事:它是真实索引的副本,里面所有的压缩包都换成同一个很小的 SDK。这个 SDK 里有一个 `flutter/bin/flutter` 脚本和一个真正的 git 仓库,所以清单和漂移检查都是真的在运行。请在 Linux 上、仓库根目录里运行。它会把 `HOME` 和 `VFOX_HOME` 设成一个临时目录(vfox 需要这两个都设),所以你真正的 vfox 不会受影响。 +一个压缩包有 1.6 到 2.3 GB,所以试验解析方面的改动,用一个假镜像更省事:它是真实索引的副本,里面所有的压缩包都换成同一个很小的 SDK。这个 SDK 里有一个 `flutter/bin/flutter` 脚本和一个真正的 git 仓库,所以收据和漂移检查都是真的在运行。请在 Linux 上、仓库根目录里运行。它会把 `HOME` 和 `VFOX_HOME` 设成一个临时目录(vfox 需要这两个都设),所以你真正的 vfox 不会受影响。 ```bash work=$(mktemp -d) @@ -202,7 +204,7 @@ done - **新的命名或选择方式。** 改 `hooks/available.lua`(顺序)或 `hooks/pre_install.lua`(选择),在 `tests/hooks_test.lua` 里加一个用例,并更新 [versions.md](versions.md)、[channels.md](channels.md) 和 [arm64.md](arm64.md) 里描述它的地方。 - **新平台。** `lib/util.lua` 里的 `getOsTypeAndArch` 列出了支持的 CPU。从 git 安装的平台,要把自己加进 `lib/source.lua` 的 `SOURCE_INSTALL_PLATFORMS` 和 `OLDEST_NATIVE`。更新 [platforms.md](platforms.md) 和 [arm64.md](arm64.md) 里的表,有运行器的话,还要把它加进容器测试([e2e.md](e2e.md))。 - **新的构建来源**,像 OpenHarmony 那样:在 `lib/` 里加一个列出名字并负责检出的模块,在 `Available`、`PreInstall` 和 `PostInstall` 里加一个分支,在 `tests/e2e/common/common.go` 里加一个版本类别(`DefaultFlavours`、`DefaultOhosVersion`),再在 `docs/` 里加一页。 -- **某条提示。** 容器测试断言了漂移警告的一部分(`tests/e2e/linux/verify.go` 和 `tests/e2e/windows/verify.go`)。要把 Lua 和这两个文件一起改,还有 [flutter-upgrade.md](flutter-upgrade.md) 里的文字。 +- **某条提示。** 容器测试断言的是核心报出的漂移(`tests/e2e/linux/verify.go` 和 `tests/e2e/windows/verify.go`)。要把 Lua 和这两个文件一起改,还有 [flutter-upgrade.md](flutter-upgrade.md) 里的文字。 ## 已知缺口 @@ -216,7 +218,7 @@ done ## 发布 -维护者在默认分支上执行 **Actions → Plugin → Run workflow**,填入不带 `v` 的版本号。共享工作流做了什么,见 [README](../../README_CN.md#发布这个插件)。之后 [vfox-plugins](https://github.com/version-fox/vfox-plugins) 里的 `plugins/flutter.json` 会显示 `vfox add flutter` 提供的版本。这比发布晚几个小时:0.2.2 晚了 1 小时 22 分钟,0.2.3 晚了 4 小时,0.2.4 晚了 2 小时 28 分钟。然后把文档更新到位,两种语言都要:把 [changes.md](changes.md) 里“未发布”下的条目挪到新版本下面,标上发布当天的日期,在它的第一段里把新版本写成最新的发布版,把它写进 [flutter-upgrade.md](flutter-upgrade.md#检查如何进行) 里清单的 `plugin_version`,并去掉其他页面里的“未发布”标记,见[编写文档](#编写文档)。 +维护者在默认分支上执行 **Actions → Plugin → Run workflow**,填入不带 `v` 的版本号。共享工作流做了什么,见 [README](../../README_CN.md#发布这个插件)。之后 [vfox-plugins](https://github.com/version-fox/vfox-plugins) 里的 `plugins/flutter.json` 会显示 `vfox add flutter` 提供的版本。这比发布晚几个小时:0.2.2 晚了 1 小时 22 分钟,0.2.3 晚了 4 小时,0.2.4 晚了 2 小时 28 分钟。然后把文档更新到位,两种语言都要:把 [changes.md](changes.md) 里“未发布”下的条目挪到新版本下面,标上发布当天的日期,在它的第一段里把新版本写成最新的发布版,并去掉其他页面里的“未发布”标记,见[编写文档](#编写文档)。 ## 编写文档 diff --git a/docs/zh-CN/flutter-upgrade.md b/docs/zh-CN/flutter-upgrade.md index 64614a4..102477e 100644 --- a/docs/zh-CN/flutter-upgrade.md +++ b/docs/zh-CN/flutter-upgrade.md @@ -15,82 +15,73 @@ vfox use --global flutter@3.47.4 ## 恢复已漂移的 SDK -如果你已经就地升级过了,这个插件会在每次 `vfox use` 那个版本时打印一条警告,并给出恢复它的命令: +如果你已经就地升级过了,用下面这条命令恢复那个版本: ```bash -vfox uninstall flutter@3.47.0 -vfox install flutter@3.47.0 -vfox use flutter@3.47.0 +vfox install --reinstall flutter@3.47.0 ``` +`vfox doctor` 会报告同一个问题(`sdk.drift`)。通过 `vfox link` 登记的 SDK 变了,只会作为提示出现:vfox 并不拥有那个 SDK。 + ## 警告内容 -SDK 的 HEAD 不再是 vfox 安装时的那个提交之后,`vfox use flutter@3.47.4` 打印的就是这样: +这需要 vfox 1.1.0 或更新的版本,它会在安装时记下 SDK 的状态,每次 `vfox use` 再拿来比对。SDK 的 HEAD 不再是 vfox 安装时的那个提交之后,`vfox use flutter@3.47.4` 打印的就是这样: ``` -Warning: flutter SDK at ~/.vfox/cache/flutter/v-3.47.4 has drifted from the version vfox installed. - vfox installed: flutter@3.47.4 (git HEAD 9584c6713b324636289d067944a46fd6b49df14b) - current git HEAD: abaf9c523780a608bd46686fd5e53740a07077f8 - reason: the SDK's git HEAD no longer matches the commit vfox installed - -This typically happens when `flutter upgrade` or a similar in-place command -is run inside a vfox-managed SDK. vfox manages SDK versions by directory and -does not track in-place mutations, so the version you get may differ from -the one you asked for. - -To restore flutter@3.47.4: - vfox uninstall flutter@3.47.4 - vfox install flutter@3.47.4 - vfox use flutter@3.47.4 - -To upgrade to a newer version, use vfox directly: - vfox install flutter@ - vfox use flutter@ +flutter@3.47.4 has changed since vfox installed it (head: 9584c6713b32… -> abaf9c523780…). + Something modified the SDK in place, for example a self-update command. vfox manages versions by directory and does not track that. + To move to a newer version, install it with vfox instead: vfox install flutter@ + Fix: vfox install --reinstall flutter@3.47.4 ``` -原因有两种,`reason:` 后面的那行说明是哪一种: +`head:` 后面先是记下来的提交,再是现在的提交,都缩短显示了。当前 HEAD 完全读不出来时(`.git` 损坏了),那里会写 `unreadable`,而不是一个提交。 -| 原因 | 含义 | -| --- | --- | -| `the SDK's git HEAD no longer matches the commit vfox installed` | 提交变了。`flutter upgrade`、`flutter downgrade`、`flutter channel` 和 `git checkout` 都会这样 | -| `vfox can no longer read the SDK's git HEAD (its .git may be broken)` | `git` 在 SDK 里执行失败:`.git` 目录损坏了,或者 `git` 已经不在了 | +警告只是警告:`vfox use` 仍然会选中你要的版本,退出码是 0。没有 `.git` 目录的 SDK 不检查。 -第一行里的路径,就是 `vfox info flutter@3.47.4` 打印的目录。SDK 是它里面的 `flutter-3.47.4` 目录。 +vfox 老于 1.1.0 时,插件会打印它自己的警告(它加载不到 `Fingerprint` 钩子),并给出手工重装的命令。把 vfox 升级到 1.1.0 或更新,就能用上面的检查。 ## 检查如何进行 -安装时,插件会在 SDK 的 `.git` 旁边写一个 `.vfox-manifest` 文件,记录预期的 git HEAD,之后每次 `vfox use` 都会重新检查。 - -清单是 SDK 根目录里的一个小 JSON 文件,`flutter-3.47.4/.vfox-manifest`: +安装时和 `vfox link` 登记时,插件通过 `Fingerprint` 钩子报告 SDK 检出所在的提交:只从文件里读 `.git/HEAD`(以及它指向的 ref 或 `packed-refs`),不跑任何命令。vfox 把这个事实记在版本的收据里,也就是 `vfox info flutter@3.47.4` 打印的那个目录下的 `.vfox-receipt.json`: ```json -{"expected_head":"9584c6713b324636289d067944a46fd6b49df14b","installed_at":1792523751,"plugin":"vfox-flutter","plugin_version":"0.2.5","version":"3.47.4"} +{ + "schema": 1, + "sdk": "flutter", + "version": "3.47.4", + "origin": "installed", + "facts": { + "head": "9584c6713b324636289d067944a46fd6b49df14b" + } +} ``` -`expected_head` 是 vfox 刚解压完 SDK 时 `git rev-parse HEAD` 打印的结果,`installed_at` 是安装时间,单位是自 1970 年以来的秒数。`vfox use` 时检查会再执行一次 `git rev-parse HEAD`,并比较两者。压缩包安装、源码安装和 OpenHarmony 构建版本都会有清单。在 SDK 里执行 `git status`,这个文件会显示为未跟踪。 +`vfox use` 和 `vfox doctor` 在事实对不上时报告 `sdk.drift`。压缩包安装、源码安装和 OpenHarmony 构建版本都会报告。插件现在读不出来的事实,也算是一种变化。 -警告只是警告:`vfox use` 仍然会选中你要的版本,退出码是 0。没有 `.git` 目录的 SDK 不检查。 - -没有可比较的东西时就什么都不检查:没有清单的 SDK(由早于 0.2.3 的插件安装的)、清单里没有 `expected_head` 的(安装时没有 `git`),以及 vfox 不认识的版本,都不会有任何提示。 +没有可比较的东西时就什么都不检查:没有事实的 SDK(安装时就没有 `.git` 可读)、vfox 开始记收据之前安装的版本(见下面的 `vfox doctor --adopt`),以及 vfox 不认识的版本,都不会有任何提示。 -## 关闭检查 +比这个插件更老的版本装出来的 SDK,根目录里可能还留着 `.vfox-manifest` 文件(`flutter-3.47.0/.vfox-manifest`)。当前插件既不写它也不读它,它会被忽略,可以删掉。留着的时候,在 SDK 里执行 `git status` 会把它显示为未跟踪。 -删掉受影响那份安装里的 `.vfox-manifest` 文件。这个文件是真正的安装才会写出来的,所以只有卸载再重新安装那个版本,它才会回来;单独执行 `vfox install` 会跳过已经安装的版本,文件依然不存在。 +在 vfox 开始记收据之前安装的版本,没有收据可比。`vfox doctor` 会说明(`sdk.no-receipt`),并可以按要求把现在的状态记为基准: -`vfox info --format '{{.Path}}' flutter@3.47.0` 打印的是 SDK 上一层的目录,所以清单在更下一层的 `flutter-3.47.0` 里。这个目录以已安装的名字命名,如果你安装时带了架构后缀,它也会带(`flutter-3.47.0-x64`)。 +```bash +vfox doctor --adopt flutter@3.47.0 +``` -### Ubuntu 26.04.1 +## 关闭检查 -在 Bash 中执行: +这个检查是 `vfox use` 选中版本后运行的快速检查之一。要停掉它们: ```bash -rm "$(vfox info --format '{{.Path}}' flutter@3.47.0)/flutter-3.47.0/.vfox-manifest" +vfox config diagnostics.onUse false ``` -### Windows 11 +只想让某一个版本不再报这一项,在 `config.yaml` 里把它加到 `diagnostics.ignore`: -这里假设已经装好了 PowerShell 7,在 PowerShell 7 中执行: - -```powershell -Remove-Item "$(vfox info --format '{{.Path}}' flutter@3.47.0)/flutter-3.47.0/.vfox-manifest" +```yaml +diagnostics: + ignore: + - "sdk.drift:flutter@3.47.0" ``` + +其余的检查项,见 vfox 的[配置说明](https://vfox.dev/zh-hans/guides/configuration.html#diagnostics-settings)和 [`vfox doctor`](https://vfox.dev/zh-hans/usage/core-commands.html#doctor)。 diff --git a/docs/zh-CN/platforms.md b/docs/zh-CN/platforms.md index b0526dd..406e04c 100644 --- a/docs/zh-CN/platforms.md +++ b/docs/zh-CN/platforms.md @@ -20,7 +20,7 @@ OpenHarmony 构建版本在每种机器上都是从 gitcode.com 检出的,见 ## 前提条件 - **vfox**,并且已经挂载到 Shell,这样 `vfox use` 之后 `flutter` 才在 `PATH` 里,见 vfox 的[快速入门](https://vfox.dev/zh-hans/guides/quick-start.html)。插件声明 vfox 0.3.0 是它能加载的最老版本。测试跑的是最新的 vfox 发布版和 vfox 的 `main`;主目录里带空格的 Windows 账户需要 vfox 1.0.13 或更新的版本([vfox#712](https://github.com/version-fox/vfox/pull/712))。 -- **`git`**:Linux ARM64 和 Windows ARM64 的每次安装、OpenHarmony 构建版本,以及 [flutter-upgrade.md](flutter-upgrade.md) 里的漂移检查都要用。漂移检查在安装时向 `git` 要 SDK 的提交;没有 `git` 时安装依然会成功,写出的 `.vfox-manifest` 里没有提交,`vfox use` 永远不会警告。Flutter 本身也需要 `git`。 +- **`git`**:Linux ARM64 和 Windows ARM64 的每次安装,以及 OpenHarmony 构建版本都要用。[flutter-upgrade.md](flutter-upgrade.md) 里的漂移检查只从文件读 SDK 的 `.git/HEAD`,不需要 `git` 可执行文件:没有 `.git` 可读的 SDK 就没有可比的事实。Flutter 本身也需要 `git`。 - **Flutter 自己的工具。** Android、iOS、Linux、Windows 和 Web 开发各有各的要求(Android SDK、Xcode、Visual Studio、GTK 等等),vfox 不会安装它们,见 [Flutter 的安装指南](https://docs.flutter.cn/install)。[README](../../README_CN.md#安装) 里的示例为 Ubuntu 装了 `curl git unzip xz-utils zip libglu1-mesa`。 - **磁盘空间。** 压缩包 1.6 到 2.3 GB(见 [versions.md](versions.md#安装)),vfox 解压后会把它删掉。Flutter 工具会为你要构建的平台下载所需的内容,SDK 会随之变大。源码安装还要给检出留出空间。你安装的每个名字都是一个独立的 SDK,见 [versions.md](versions.md#已安装的名称)。 diff --git a/docs/zh-CN/troubleshooting.md b/docs/zh-CN/troubleshooting.md index 40188e9..4a03669 100644 --- a/docs/zh-CN/troubleshooting.md +++ b/docs/zh-CN/troubleshooting.md @@ -28,7 +28,7 @@ failed to install flutter ### `flutter@3.47.4 is already installed` -这个名字已经安装了。vfox 不会再下载,也不会重新写 `.vfox-manifest`,见 [flutter-upgrade.md](flutter-upgrade.md#关闭检查)。 +这个名字已经安装了。vfox 不会再下载。要用全新的拷贝替换它,比如 `flutter upgrade` 已经把它就地改动过,执行 `vfox install --reinstall flutter@3.47.4`,见 [flutter-upgrade.md](flutter-upgrade.md#恢复已漂移的-sdk)。 ### `get version failed: ... (status ...)` @@ -59,9 +59,9 @@ vfox 下载了压缩包,它的 SHA-256 和 Flutter 发布索引里的不一样 插件现在只列这种文件最新的那一条,所以这三个版本都能装。0.2.5 之前的版本把所有条目都列出来,装排在最前面的那条。在 0.2.4 里,条目相同时顺序是任意的,还取决于列表的其余部分,比如其中有多少个 OpenHarmony 版本。2026-10-21 时,它在 Linux x64 上三个全都取了旧条目,在 macOS 和 Windows 上也有一部分,安装就会像上面这样结束。请更新插件,或者装它旁边的版本(用 `3.13.2` 或 `3.13.4` 代替 `3.13.3`)。没有跳过校验的开关。 -### `Warning: flutter SDK at ... has drifted from the version vfox installed.` +### `flutter@3.47.4 has changed since vfox installed it` -`flutter upgrade`、`flutter channel` 或某条 `git` 命令移动了 SDK。`vfox use` 仍然会选中它。见 [flutter-upgrade.md](flutter-upgrade.md)。 +`flutter upgrade`、`flutter channel` 或某条 `git` 命令移动了 SDK。`vfox use` 仍然会选中它。用 `vfox install --reinstall flutter@3.47.4` 恢复它。见 [flutter-upgrade.md](flutter-upgrade.md)。 ### `flutter does not support the 386 architecture` @@ -170,7 +170,7 @@ gitcode.com 限制匿名客户端的请求次数。超出限制时它回答 HTTP - **Flutter 说“A new version of Flutter is available!”并建议执行 `flutter upgrade`。** 别理它:`flutter upgrade` 会在 vfox 的背后改动 SDK,见 [flutter-upgrade.md](flutter-upgrade.md)。`vfox install flutter@stable` 才是升级。`flutter --no-version-check` 可以不显示这条提示。 - **`FLUTTER_ROOT` 没有设置。** 插件只设置 `PATH`。`flutter` 脚本会自己找到它所在的目录。 - **没有装 Dart 插件,`dart` 却在。** Flutter SDK 包含 Dart SDK,`dart` 就在它的 `bin` 里。不需要再另外添加 [vfox-dart](https://github.com/version-fox/vfox-dart) 插件。 -- **`.vfox-manifest` 在 SDK 的 git 里是未跟踪的。** 这是插件写的,见 [flutter-upgrade.md](flutter-upgrade.md)。 +- **`.vfox-manifest` 在 SDK 的 git 里是未跟踪的。** 这是这个插件 `Fingerprint` 钩子之前的版本写的,当前插件既不写它也不读它,可以删掉。见 [flutter-upgrade.md](flutter-upgrade.md#检查如何进行)。 - **在中国,`flutter pub get` 很慢或者失败。** 包是从 `PUB_HOSTED_URL` 拉取的,插件不会去动它,见 [mirror.md](mirror.md#哪种安装用哪个镜像)。 - **第一次执行 `flutter` 命令会下载很多东西。** Flutter 工具在你第一次为某个平台构建时才拉取所需的内容,而且它为此读取 `FLUTTER_STORAGE_BASE_URL`,所以要一直保持镜像变量处于设置状态,见 [mirror.md](mirror.md#这个变量的作用)。 diff --git a/hooks/fingerprint.lua b/hooks/fingerprint.lua new file mode 100644 index 0000000..065a272 --- /dev/null +++ b/hooks/fingerprint.lua @@ -0,0 +1,47 @@ +-- Copyright 2026 Han Li and contributors +-- +-- Licensed under the Apache License, Version 2.0 (the "License"); +-- you may not use this file except in compliance with the License. +-- You may obtain a copy of the License at +-- +-- http://www.apache.org/licenses/LICENSE-2.0 +-- +-- Unless required by applicable law or agreed to in writing, software +-- distributed under the License is distributed on an "AS IS" BASIS, +-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +-- See the License for the specific language governing permissions and +-- limitations under the License. + +local manifest = require("manifest") + +-- The fact that identifies a Flutter installation: the commit its git +-- checkout is at. vfox records it in the version's receipt on install and +-- link, and `vfox use` and `vfox doctor` warn when it is no longer the same +-- (for example after `flutter upgrade` moved the SDK in place), with +-- `vfox install --reinstall` as the way out. +-- +-- The hook runs on every `vfox use`, so it only reads files: no processes, no +-- network. A nil return means there is nothing to check (no `.git`), and vfox +-- stays silent: SDKs without a git checkout are left alone. +function PLUGIN:Fingerprint(ctx) + if type(ctx) ~= "table" then + return nil + end + local path = ctx.path + local version = ctx.version + local head = manifest.fingerprintHead(path, version) + if (head == nil or head == "") and ctx.sdkInfo ~= nil and PLUGIN ~= nil and PLUGIN.name ~= nil then + local info = ctx.sdkInfo[PLUGIN.name] + if info ~= nil and type(info.path) == "string" and info.path ~= path then + head = manifest.fingerprintHead(info.path, version or info.version) + end + end + if head == nil or head == "" then + return nil + end + return { + facts = { + head = head, + }, + } +end diff --git a/hooks/pre_install.lua b/hooks/pre_install.lua index 4d09f0e..64d11f5 100644 --- a/hooks/pre_install.lua +++ b/hooks/pre_install.lua @@ -80,7 +80,12 @@ function PLUGIN:PostInstall(ctx) return end if sdk.path ~= nil and sdk.path ~= "" then - pcall(manifest.write, sdk.path, sdk) + -- vfox 1.1.0 records the Fingerprint fact in the version's receipt, so + -- the `.vfox-manifest` file is only written for older vfox which never + -- loads `hooks/fingerprint.lua` and still needs it for `PreUse`. + if not supportsFingerprint(ctx and ctx.runtimeVersion) then + pcall(manifest.write, sdk.path, sdk) + end pcall(manifest.touchPubspecLock, sdk.path) end if ohos.isOhosVersion(sdk.version) then diff --git a/hooks/pre_use.lua b/hooks/pre_use.lua index ac6079f..c78183b 100644 --- a/hooks/pre_use.lua +++ b/hooks/pre_use.lua @@ -14,6 +14,8 @@ local manifest = require("manifest") +require("util") + local REASON = { ["head-drifted"] = "the SDK's git HEAD no longer matches the commit vfox installed", ["sdk-no-longer-git"] = "vfox can no longer read the SDK's git HEAD (its .git may be broken)", @@ -58,6 +60,14 @@ To upgrade to a newer version, use vfox directly: end function PLUGIN:PreUse(ctx) + -- vfox 1.1.0 records the Fingerprint fact in the version's receipt and + -- reports drift itself (`sdk.drift` after `vfox use` and in `vfox doctor`, + -- fixed with `vfox install --reinstall`). Printing the plugin's own + -- warning as well would report the same problem twice, so the check below + -- only runs on older vfox which never loads `hooks/fingerprint.lua`. + if supportsFingerprint(ctx and ctx.runtimeVersion) then + return { version = ctx.version } + end local sdk = ctx.installedSdks and ctx.installedSdks[ctx.version] if sdk == nil or sdk.path == nil or sdk.path == "" then return { version = ctx.version } diff --git a/lib/manifest.lua b/lib/manifest.lua index 1b1378c..b6d12f1 100644 --- a/lib/manifest.lua +++ b/lib/manifest.lua @@ -80,6 +80,90 @@ local function isEmptyTable(table) return next(table) == nil end +local function trim(s) + if type(s) ~= "string" then + return nil + end + local t = s:match("^(.-)%s*$") + if t == "" then + return nil + end + return t +end + +local function readTrimmed(path) + local f = io.open(path, "r") + if f == nil then + return nil + end + local content = f:read("*a") + f:close() + return trim(content) +end + +-- The git directory of an SDK, without running any process. `sdkRoot` is the +-- SDK itself (what Fingerprint gets as `ctx.path`); `version` covers the older +-- layout where the hook was given the version directory that holds +-- `flutter-`. Returns nil when there is no `.git/HEAD` to read. +local function gitDirFor(sdkRoot, version) + if type(sdkRoot) ~= "string" or sdkRoot == "" then + return nil + end + if hasGitDir(sdkRoot) then + return joinPath(sdkRoot, ".git") + end + if type(version) == "string" and version ~= "" then + local candidate = joinPath(sdkRoot, "flutter-" .. version) + if hasGitDir(candidate) then + return joinPath(candidate, ".git") + end + end + return nil +end + +local function headFromPackedRefs(gitDir, ref) + local packed = readTrimmed(joinPath(gitDir, "packed-refs")) + if packed == nil then + return nil + end + for line in (packed .. "\n"):gmatch("(.-)\n") do + line = trim(line) + if line ~= nil and line:sub(1, 1) ~= "#" and line:sub(1, 1) ~= "^" then + local hash, name = line:match("^(%x+)%s+(%S+)$") + if hash ~= nil and name == ref then + return hash + end + end + end + return nil +end + +local function headFromHeadFile(gitDir) + local head = readTrimmed(joinPath(gitDir, "HEAD")) + if head == nil then + return nil + end + local ref = head:match("^ref:%s*(.+)$") + if ref == nil then + -- Detached HEAD: the file holds the commit itself. + if head:match("^[0-9a-fA-F]+$") ~= nil then + return head + end + return nil + end + ref = trim(ref) + if ref == nil then + return nil + end + -- A slash in a ref is a path separator inside `.git`, even on Windows. + local refPath = gitDir .. "/" .. ref + local hash = readTrimmed(refPath) + if hash ~= nil then + return hash + end + return headFromPackedRefs(gitDir, ref) +end + local M = {} function M.gitRoot(sdkRoot) @@ -193,6 +277,20 @@ function M.checkDrift(sdkRoot) return false, "ok" end +-- The commit the SDK checkout is at, read from files only: no processes, no +-- network, fast enough for the Fingerprint hook which runs on every +-- `vfox use`. Returns nil when there is nothing to check (no `.git`, an +-- unreadable HEAD), so the caller returns no facts and vfox stays silent. +-- `version` is the installed name (`ctx.version`); it only covers the older +-- layout where the SDK lives in `flutter-` below the given path. +function M.fingerprintHead(sdkRoot, version) + local gitDir = gitDirFor(sdkRoot, version) + if gitDir == nil then + return nil + end + return headFromHeadFile(gitDir) +end + -- vfox extracts archives with Go's archive/tar (see -- internal/shared/util/decompressor.go), which creates files with the -- extraction time instead of the mtime stored in the archive. The official diff --git a/lib/util.lua b/lib/util.lua index 23d0f08..d3ed9e8 100644 --- a/lib/util.lua +++ b/lib/util.lua @@ -86,3 +86,26 @@ function compare_versions(v1, v2) return 0 end + +-- Whether the running vfox knows the Fingerprint hook (added in vfox 1.1.0 +-- with `vfox link`, `vfox doctor`, aliases and `path.mode`). Older vfox +-- versions never load a hook file they do not know, so the plugin keeps its +-- own drift check for them and lets the core report drift on newer ones. +-- `runtimeVersion` is the `ctx.runtimeVersion` of the calling hook when it +-- has one; otherwise the global `RUNTIME.version` answers. +function supportsFingerprint(runtimeVersion) + local v = runtimeVersion + if v == nil or v == "" then + v = (RUNTIME and RUNTIME.version) or "" + end + v = tostring(v):gsub("^v", "") + local major, minor = v:match("^(%d+)%.(%d+)") + if major == nil then + return false + end + major, minor = tonumber(major), tonumber(minor) + if major == nil or minor == nil then + return false + end + return major > 1 or (major == 1 and minor >= 1) +end diff --git a/tests/e2e/common/common.go b/tests/e2e/common/common.go index 6800b67..5d6c7c3 100644 --- a/tests/e2e/common/common.go +++ b/tests/e2e/common/common.go @@ -317,7 +317,15 @@ func ContainerName(slug string) string { return "vfox-flutter-e2e-" + slug + "-" + hex.EncodeToString(b[:]) } -// Manifest is the anchored-install record the plugin writes into the SDK. +// Manifest is the anchored-install record the plugin wrote into the SDK +// before the Fingerprint hook (plugin versions before the receipt). type Manifest struct { ExpectedHead string `json:"expected_head"` } + +// Receipt is what vfox 1.1.0+ records in the version directory +// (`.vfox-receipt.json`): where the version came from and, when the plugin +// implements Fingerprint, the facts that identify it. +type Receipt struct { + Facts map[string]string `json:"facts"` +} diff --git a/tests/e2e/linux/verify.go b/tests/e2e/linux/verify.go index 4c7d375..324bf6b 100644 --- a/tests/e2e/linux/verify.go +++ b/tests/e2e/linux/verify.go @@ -28,9 +28,10 @@ import ( "github.com/version-fox/vfox-flutter/tests/e2e/common" ) -// NOTE: the drift-warning strings asserted here are part of the plugin's -// user-facing contract (see hooks/ lib/). If the Lua side rewords them, -// update this file and tests/e2e/windows/verify.go together. +// NOTE: the drift strings asserted here are the core's user-facing contract +// for `sdk.drift` (see `vfox doctor`), fed by the plugin's Fingerprint hook. +// If vfox rewords them, update this file and tests/e2e/windows/verify.go +// together. // sdkDir prints the SDK root for the active flutter on PATH // (was lib.sh sdk_dir). @@ -59,34 +60,35 @@ func verifySdkLayout(ctx context.Context, t *testing.T, ctr tc.Container, flavor t.Log("PASS the OpenHarmony SDK is a git checkout with its engine pins tracked") } -// verifyManifestDrift anchors the installed HEAD via .vfox-manifest, proves -// `vfox use` reports drift exactly when the SDK moves (simulated -// `flutter upgrade`), and goes quiet again once restored. +// verifyManifestDrift anchors the installed HEAD via the version's receipt +// (`.vfox-receipt.json`, written from the Fingerprint hook), proves `vfox use` +// reports `sdk.drift` exactly when the SDK moves (simulated `flutter upgrade`), +// and goes quiet again once restored. func verifyManifestDrift(ctx context.Context, t *testing.T, ctr tc.Container, version, sdk string) { t.Helper() - manifestPath := sdk + "/.vfox-manifest" - raw := execOK(ctx, t, ctr, fmt.Sprintf("cat %q", manifestPath)) - var m common.Manifest - if err := json.Unmarshal([]byte(raw), &m); err != nil { - t.Fatalf("the .vfox-manifest is not valid JSON: %v\n--- actual ---\n%s", err, raw) + receiptPath := path.Dir(sdk) + "/.vfox-receipt.json" + raw := execOK(ctx, t, ctr, fmt.Sprintf("cat %q", receiptPath)) + var r common.Receipt + if err := json.Unmarshal([]byte(raw), &r); err != nil { + t.Fatalf("the .vfox-receipt.json is not valid JSON: %v\n--- actual ---\n%s", err, raw) } - if m.ExpectedHead == "" { - t.Fatal("the .vfox-manifest has no expected_head") + anchor := r.Facts["head"] + if anchor == "" { + t.Fatal("the receipt has no head fact") } - anchor := m.ExpectedHead - t.Log("PASS the SDK carries a .vfox-manifest") + t.Log("PASS the version carries a receipt with the Fingerprint head") installedHead := strings.TrimSpace(execOK(ctx, t, ctr, fmt.Sprintf("git -C %q rev-parse HEAD", sdk))) if anchor != installedHead { - t.Fatalf("the .vfox-manifest anchor %s does not match the installed git HEAD %s", anchor, installedHead) + t.Fatalf("the receipt anchor %s does not match the installed git HEAD %s", anchor, installedHead) } - t.Log("PASS the .vfox-manifest anchor matches the installed git HEAD") + t.Log("PASS the receipt anchor matches the installed git HEAD") use := func() string { return execOK(ctx, t, ctr, activated(fmt.Sprintf("vfox use --global flutter@%s", version))) } - require.NotContains(t, use(), "has drifted", "a freshly installed SDK reports no drift") + require.NotContains(t, use(), "has changed since vfox installed it", "a freshly installed SDK reports no drift") execOK(ctx, t, ctr, fmt.Sprintf("git -C %q commit --allow-empty --quiet -m 'simulated flutter upgrade'", sdk), "GIT_AUTHOR_NAME=e2e", @@ -95,17 +97,24 @@ func verifyManifestDrift(ctx context.Context, t *testing.T, ctr tc.Container, ve "GIT_COMMITTER_EMAIL=e2e@vfox.flutter") driftedHead := strings.TrimSpace(execOK(ctx, t, ctr, fmt.Sprintf("git -C %q rev-parse HEAD", sdk))) + short := func(h string) string { + if len(h) > 12 { + return h[:12] + "…" + } + return h + } + drifted := use() - require.Contains(t, drifted, "has drifted from the version vfox installed", "drift warning") - require.Contains(t, drifted, anchor, "drift warning expected head") - require.Contains(t, drifted, driftedHead, "drift warning current head") - require.Contains(t, drifted, "vfox uninstall flutter@"+version, "drift warning restore command") - require.Contains(t, drifted, "vfox install flutter@"+version, "drift warning restore command") - require.Contains(t, drifted, "vfox use flutter@"+version, "drift warning restore command") + require.Contains(t, drifted, "has changed since vfox installed it", "drift warning") + require.Contains(t, drifted, "head: "+short(anchor)+" -> "+short(driftedHead), "drift warning heads") + require.Contains(t, drifted, "vfox install --reinstall flutter@"+version, "drift warning reinstall command") require.Contains(t, drifted, "vfox install flutter@", "drift warning upgrade command") + doctor := execOK(ctx, t, ctr, activated(fmt.Sprintf("vfox doctor flutter@%s", version))) + require.Contains(t, doctor, "has changed since vfox installed it", "vfox doctor reports the same drift") + execOK(ctx, t, ctr, fmt.Sprintf("git -C %q reset --quiet --hard %q", sdk, anchor)) - require.NotContains(t, use(), "has drifted", "a restored SDK reports no drift") + require.NotContains(t, use(), "has changed since vfox installed it", "a restored SDK reports no drift") } // verifyFirstRunMatchesOfficial proves a freshly installed archive SDK diff --git a/tests/e2e/windows/verify.go b/tests/e2e/windows/verify.go index a15822f..3dd59df 100644 --- a/tests/e2e/windows/verify.go +++ b/tests/e2e/windows/verify.go @@ -27,9 +27,10 @@ import ( "github.com/version-fox/vfox-flutter/tests/e2e/common" ) -// NOTE: the drift-warning strings asserted here are part of the plugin's -// user-facing contract (see hooks/ lib/). If the Lua side rewords them, -// update this file and tests/e2e/linux/verify.go together. +// NOTE: the drift strings asserted here are the core's user-facing contract +// for `sdk.drift` (see `vfox doctor`), fed by the plugin's Fingerprint hook. +// If vfox rewords them, update this file and tests/e2e/linux/verify.go +// together. // winDir is filepath.Dir for container paths, which always use backslashes // even when the test binary itself runs on a non-Windows host. @@ -70,31 +71,41 @@ func verifySdkLayout(ctx context.Context, t *testing.T, ctr tc.Container, box sl t.Log("PASS the OpenHarmony SDK is a git checkout with its engine pins tracked") } -// manifestAnchor reads .vfox-manifest and returns its expected_head. -func manifestAnchor(ctx context.Context, t *testing.T, ctr tc.Container, box slotBox, sdk string) string { +// receiptAnchor reads the version's receipt (`.vfox-receipt.json`, written +// from the Fingerprint hook) and returns its head fact. +func receiptAnchor(ctx context.Context, t *testing.T, ctr tc.Container, box slotBox, sdk string) string { t.Helper() + versionDir := winDir(sdk) raw := execOK(ctx, t, ctr, - "Get-Content -Raw "+pwshQuote(sdk+`\.vfox-manifest`), box.vars...) - var m common.Manifest - if err := json.Unmarshal([]byte(raw), &m); err != nil { - t.Fatalf("the .vfox-manifest is not valid JSON: %v\n--- actual ---\n%s", err, raw) + "Get-Content -Raw "+pwshQuote(versionDir+`\.vfox-receipt.json`), box.vars...) + var r common.Receipt + if err := json.Unmarshal([]byte(raw), &r); err != nil { + t.Fatalf("the .vfox-receipt.json is not valid JSON: %v\n--- actual ---\n%s", err, raw) } - require.NotEmpty(t, m.ExpectedHead, "the .vfox-manifest has no expected_head") - return m.ExpectedHead + require.NotEmpty(t, r.Facts["head"], "the receipt has no head fact") + return r.Facts["head"] } -// verifyManifestDrift anchors the installed HEAD via .vfox-manifest, proves -// `vfox use` reports drift exactly when the SDK moves (simulated +// shortHead shortens a commit the way vfox does in the drift message. +func shortHead(h string) string { + if len(h) > 12 { + return h[:12] + "…" + } + return h +} + +// verifyManifestDrift anchors the installed HEAD via the version's receipt, +// proves `vfox use` reports `sdk.drift` exactly when the SDK moves (simulated // `flutter upgrade`), and goes quiet again once restored. func verifyManifestDrift(ctx context.Context, t *testing.T, ctr tc.Container, box slotBox, activation, version, sdk string) { t.Helper() - anchor := manifestAnchor(ctx, t, ctr, box, sdk) - t.Log("PASS the SDK carries a .vfox-manifest") + anchor := receiptAnchor(ctx, t, ctr, box, sdk) + t.Log("PASS the version carries a receipt with the Fingerprint head") installedHead := strings.TrimSpace(execOK(ctx, t, ctr, "git -C "+pwshQuote(sdk)+" rev-parse HEAD", box.vars...)) - require.Equal(t, installedHead, anchor, "the .vfox-manifest anchor does not match the installed git HEAD") - t.Log("PASS the .vfox-manifest anchor matches the installed git HEAD") + require.Equal(t, installedHead, anchor, "the receipt anchor does not match the installed git HEAD") + t.Log("PASS the receipt anchor matches the installed git HEAD") use := func() string { return execOK(ctx, t, ctr, @@ -102,7 +113,7 @@ func verifyManifestDrift(ctx context.Context, t *testing.T, ctr tc.Container, bo box.vars...) } - require.NotContains(t, use(), "has drifted", "a freshly installed SDK reports no drift") + require.NotContains(t, use(), "has changed since vfox installed it", "a freshly installed SDK reports no drift") execOK(ctx, t, ctr, "git -C "+pwshQuote(sdk)+" commit --allow-empty -q -m 'simulated flutter upgrade'", @@ -115,17 +126,19 @@ func verifyManifestDrift(ctx context.Context, t *testing.T, ctr tc.Container, bo "git -C "+pwshQuote(sdk)+" rev-parse HEAD", box.vars...)) drifted := use() - require.Contains(t, drifted, "has drifted from the version vfox installed", "drift warning") - require.Contains(t, drifted, anchor, "drift warning expected head") - require.Contains(t, drifted, driftedHead, "drift warning current head") - require.Contains(t, drifted, "vfox uninstall flutter@"+version, "drift warning restore command") - require.Contains(t, drifted, "vfox install flutter@"+version, "drift warning restore command") - require.Contains(t, drifted, "vfox use flutter@"+version, "drift warning restore command") + require.Contains(t, drifted, "has changed since vfox installed it", "drift warning") + require.Contains(t, drifted, "head: "+shortHead(anchor)+" -> "+shortHead(driftedHead), "drift warning heads") + require.Contains(t, drifted, "vfox install --reinstall flutter@"+version, "drift warning reinstall command") require.Contains(t, drifted, "vfox install flutter@", "drift warning upgrade command") + doctor := execOK(ctx, t, ctr, + activatedEnv(activation, fmt.Sprintf("vfox doctor %s", pwshQuote("flutter@"+version))), + box.vars...) + require.Contains(t, doctor, "has changed since vfox installed it", "vfox doctor reports the same drift") + execOK(ctx, t, ctr, "git -C "+pwshQuote(sdk)+" reset -q --hard "+pwshQuote(anchor), box.vars...) - require.NotContains(t, use(), "has drifted", "a restored SDK reports no drift") + require.NotContains(t, use(), "has changed since vfox installed it", "a restored SDK reports no drift") } // NOTE: there is deliberately no first-run rebuild check on Windows. diff --git a/tests/hooks_test.lua b/tests/hooks_test.lua index 79b322d..807f3bb 100644 --- a/tests/hooks_test.lua +++ b/tests/hooks_test.lua @@ -584,6 +584,114 @@ tests[#tests + 1] = { end end, } +tests[#tests + 1] = { + "the running vfox is recognised as new enough for Fingerprint", + function() + setup("linux", "amd64") + assert(supportsFingerprint("1.1.0") == true) + assert(supportsFingerprint("v1.1.0") == true) + assert(supportsFingerprint("2.0.0") == true) + assert(supportsFingerprint("1.0.13") == false) + assert(supportsFingerprint("0.6.0") == false) + assert(supportsFingerprint("1.0.0") == false) + RUNTIME.version = "1.1.0" + assert(supportsFingerprint(nil) == true) + assert(supportsFingerprint("") == true) + RUNTIME.version = "1.0.13" + assert(supportsFingerprint(nil) == false) + RUNTIME.version = nil + assert(supportsFingerprint(nil) == false) + assert(supportsFingerprint("") == false) + end, +} +tests[#tests + 1] = { + "Fingerprint reads the git HEAD from files only", + function() + setup("linux", "amd64") + local manifest = require("manifest") + local base = os.tmpname() + os.remove(base) + local function write(path, text) + local dir = path:match("^(.+)/[^/]+$") + os.execute("mkdir -p '" .. dir .. "'") + local f = assert(io.open(path, "wb")) + f:write(text) + f:close() + end + local function head(path, version) + return manifest.fingerprintHead(path, version) + end + -- detached HEAD in the SDK root + write(base .. "/sdk/.git/HEAD", "abc123def456abc123def456abc123def456abcd\n") + equal(head(base .. "/sdk", "3.47.4"), "abc123def456abc123def456abc123def456abcd") + -- a ref that lives in its own file + write(base .. "/ref/.git/HEAD", "ref: refs/heads/beta\n") + write(base .. "/ref/.git/refs/heads/beta", "cafecafecafecafecafecafecafecafecafecafe\n") + equal(head(base .. "/ref", "3.47.4"), "cafecafecafecafecafecafecafecafecafecafe") + -- a ref that only lives in packed-refs + write(base .. "/packed/.git/HEAD", "ref: refs/heads/stable\n") + write( + base .. "/packed/.git/packed-refs", + "# pack-refs\ndeadbeefdeadbeefdeadbeefdeadbeefdeadbeef refs/heads/stable\n" + ) + equal(head(base .. "/packed", "3.47.4"), "deadbeefdeadbeefdeadbeefdeadbeefdeadbeef") + -- the older layout where the hook is given the version directory + write(base .. "/ver/flutter-1.0/.git/HEAD", "1111111111111111111111111111111111111111\n") + equal(head(base .. "/ver", "1.0"), "1111111111111111111111111111111111111111") + -- nothing to check is silent: no .git, no HEAD, empty path + equal(head(base .. "/nosuch", "1.0"), nil) + equal(head("", "1.0"), nil) + equal(head(base .. "/sdk", nil), "abc123def456abc123def456abc123def456abcd") + os.execute("rm -rf '" .. base .. "'") + end, +} +tests[#tests + 1] = { + "Fingerprint returns the head fact and is silent without git", + function() + setup("linux", "amd64") + dofile("hooks/fingerprint.lua") + local base = os.tmpname() + os.remove(base) + os.execute("mkdir -p '" .. base .. "/sdk/.git'") + local f = assert(io.open(base .. "/sdk/.git/HEAD", "wb")) + f:write("abc123def456abc123def456abc123def456abcd\n") + f:close() + local r = PLUGIN:Fingerprint({ path = base .. "/sdk", version = "3.47.4", sdkInfo = {} }) + assert(r ~= nil and r.facts ~= nil, "Fingerprint must report facts") + equal(r.facts.head, "abc123def456abc123def456abc123def456abcd") + assert(PLUGIN:Fingerprint({ path = base .. "/nosuch", version = "1.0", sdkInfo = {} }) == nil) + -- the main SDK info is a fallback when ctx.path is not the SDK + local r2 = PLUGIN:Fingerprint({ + path = base .. "/nosuch", + version = "3.47.4", + sdkInfo = { flutter = { path = base .. "/sdk", version = "3.47.4" } }, + }) + assert(r2 ~= nil and r2.facts.head == "abc123def456abc123def456abc123def456abcd") + os.execute("rm -rf '" .. base .. "'") + end, +} +tests[#tests + 1] = { + "PreUse skips its own warning on vfox with Fingerprint", + function() + setup("linux", "amd64") + dofile("hooks/fingerprint.lua") + dofile("hooks/pre_use.lua") + -- new vfox: no warning, no manifest read, just the version + local out = PLUGIN:PreUse({ version = "3.47.4", runtimeVersion = "1.1.0", installedSdks = {} }) + equal(out.version, "3.47.4") + -- old vfox without a manifest is silent too and still returns the version + local out2 = PLUGIN:PreUse({ + version = "3.47.4", + runtimeVersion = "1.0.13", + installedSdks = { ["3.47.4"] = { path = "/nosuch-xyz" } }, + }) + equal(out2.version, "3.47.4") + -- old vfox with RUNTIME.version only + RUNTIME.version = "1.0.13" + local out3 = PLUGIN:PreUse({ version = "3.47.4", installedSdks = {} }) + equal(out3.version, "3.47.4") + end, +} local failures = 0 for _, test in ipairs(tests) do From 5f99a64c7395d4e76ae4ed97a7f81e806b13bf0f Mon Sep 17 00:00:00 2001 From: Qiheng He Date: Tue, 10 Nov 2026 11:00:39 +0800 Subject: [PATCH 2/4] fix(e2e): resolve the global link before reading the receipt --- tests/e2e/linux/verify.go | 5 ++++- tests/e2e/windows/verify.go | 8 ++++++-- 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/tests/e2e/linux/verify.go b/tests/e2e/linux/verify.go index 324bf6b..2c4983f 100644 --- a/tests/e2e/linux/verify.go +++ b/tests/e2e/linux/verify.go @@ -66,7 +66,10 @@ func verifySdkLayout(ctx context.Context, t *testing.T, ctr tc.Container, flavor // and goes quiet again once restored. func verifyManifestDrift(ctx context.Context, t *testing.T, ctr tc.Container, version, sdk string) { t.Helper() - receiptPath := path.Dir(sdk) + "/.vfox-receipt.json" + // sdk is the global link; the receipt lives in the version directory, the + // parent of the real SDK directory, so resolve the link first. + realSdk := strings.TrimSpace(execOK(ctx, t, ctr, fmt.Sprintf("readlink -f %q", sdk))) + receiptPath := path.Dir(realSdk) + "/.vfox-receipt.json" raw := execOK(ctx, t, ctr, fmt.Sprintf("cat %q", receiptPath)) var r common.Receipt if err := json.Unmarshal([]byte(raw), &r); err != nil { diff --git a/tests/e2e/windows/verify.go b/tests/e2e/windows/verify.go index 3dd59df..9a473b9 100644 --- a/tests/e2e/windows/verify.go +++ b/tests/e2e/windows/verify.go @@ -72,10 +72,14 @@ func verifySdkLayout(ctx context.Context, t *testing.T, ctr tc.Container, box sl } // receiptAnchor reads the version's receipt (`.vfox-receipt.json`, written -// from the Fingerprint hook) and returns its head fact. +// from the Fingerprint hook) and returns its head fact. sdk is the global +// link; the receipt lives in the version directory, the parent of the real +// SDK directory, so resolve the link target first. func receiptAnchor(ctx context.Context, t *testing.T, ctr tc.Container, box slotBox, sdk string) string { t.Helper() - versionDir := winDir(sdk) + target := strings.TrimSpace(execOK(ctx, t, ctr, + "(Get-Item "+pwshQuote(sdk)+").Target", box.vars...)) + versionDir := winDir(target) raw := execOK(ctx, t, ctr, "Get-Content -Raw "+pwshQuote(versionDir+`\.vfox-receipt.json`), box.vars...) var r common.Receipt From e1c1ee9d5e0f6cb8f3db2301a01d9af756cb174b Mon Sep 17 00:00:00 2001 From: Qiheng He Date: Tue, 10 Nov 2026 11:07:44 +0800 Subject: [PATCH 3/4] docs: cover SDKs installed by other managers Homebrew, mise, asdf, winget and manual installs all ship Google's archives with .git, so the Fingerprint head fact applies to vfox link copies too (verified end to end against vfox 1.1.0: receipt, doctor info notice, no reinstall for linked, silent without .git). Document link adoption, the owned-vs-linked recovery difference, and PATH shadowing pointers. --- docs/changes.md | 2 +- docs/development.md | 2 +- docs/flutter-upgrade.md | 32 ++++++++++++++++++++++++++++++-- docs/troubleshooting.md | 2 +- docs/zh-CN/changes.md | 2 +- docs/zh-CN/development.md | 2 +- docs/zh-CN/flutter-upgrade.md | 15 ++++++++++++++- docs/zh-CN/troubleshooting.md | 2 +- 8 files changed, 50 insertions(+), 9 deletions(-) diff --git a/docs/changes.md b/docs/changes.md index a71862d..a14a1fd 100644 --- a/docs/changes.md +++ b/docs/changes.md @@ -6,7 +6,7 @@ What changed in each release, as a user notices it. GitHub's release pages and t ## Unreleased -- Drift detection goes through vfox's `Fingerprint` hook (needs vfox 1.1.0 or later): the plugin reports the SDK checkout's git HEAD from files only, vfox records it in the version's receipt and reports `sdk.drift` after `vfox use` and in `vfox doctor`, fixed with `vfox install --reinstall`. The plugin no longer writes `.vfox-manifest` on new vfox and no longer prints its own warning there, so the same drift is not reported twice; vfox older than 1.1.0 keeps the old warning. See [flutter-upgrade.md](flutter-upgrade.md). +- Drift detection goes through vfox's `Fingerprint` hook (needs vfox 1.1.0 or later): the plugin reports the SDK checkout's git HEAD from files only, vfox records it in the version's receipt and reports `sdk.drift` after `vfox use` and in `vfox doctor`, fixed with `vfox install --reinstall`. Linked copies from other managers (Homebrew, mise, asdf, winget, manual installs) are covered the same way when they still carry their `.git`, as an info-level notice that vfox does not own. The plugin no longer writes `.vfox-manifest` on new vfox and no longer prints its own warning there, so the same drift is not reported twice; vfox older than 1.1.0 keeps the old warning. See [flutter-upgrade.md](flutter-upgrade.md). ## 0.2.5 (2026-10-21) diff --git a/docs/development.md b/docs/development.md index 47679fc..ebe4d54 100644 --- a/docs/development.md +++ b/docs/development.md @@ -43,7 +43,7 @@ vfox loads `metadata.lua`, calls a hook when a command needs it, and puts `PLUGI - `PreInstall` returns `nil` for a name it cannot resolve, which vfox reports as `no installable runtime provided`. It raises an error for a failure: the message of `error()` shows up in the `plugin [PreInstall] method error:` line. - The index lists some releases more than once. `newestPublications` in `hooks/available.lua` keeps the newest entry (`release_date`) of each archive of a version, because a file that was uploaded again has the checksum of the newest entry only (see [troubleshooting.md](troubleshooting.md#checksum-error)). Different versions never merge, and a release in two channels has an archive in each and keeps both. `table.sort` is not stable, so the comparator has to tell any two entries apart, or equal entries come out in an order that depends on the whole input, and `PreInstall` takes the first match. It ends with the version and the channel for that. - `PostInstall` reads `ctx.sdkInfo[PLUGIN.name]`. It runs the `pubspec.lock` fix under `pcall`, so a failure there never fails the install. The legacy `.vfox-manifest` is only written when the running vfox is older than 1.1.0 (`supportsFingerprint` in `lib/util.lua`): newer vfox records the `Fingerprint` fact in the version's receipt instead. -- `Fingerprint` reports the commit the SDK checkout is at as `facts.head`, by reading `.git/HEAD` (and the ref or `packed-refs` it points to) from files only: no processes, no network, well under the 50 ms the hook must keep. It returns nil when there is nothing to check (no `.git`), and vfox stays silent then. Archive installs, source installs and OpenHarmony builds all report it. `PreUse` skips its own drift check on vfox 1.1.0+ (`supportsFingerprint(ctx.runtimeVersion)`) so the same drift is not reported twice; older vfox keeps the plugin's own warning from `.vfox-manifest`. +- `Fingerprint` reports the commit the SDK checkout is at as `facts.head`, by reading `.git/HEAD` (and the ref or `packed-refs` it points to) from files only: no processes, no network, well under the 50 ms the hook must keep. It returns nil when there is nothing to check (no `.git`), and vfox stays silent then. Archive installs, source installs and OpenHarmony builds all report it, as do linked copies that still carry their `.git` (Homebrew, mise, asdf, winget, manual installs). `PreUse` skips its own drift check on vfox 1.1.0+ (`supportsFingerprint(ctx.runtimeVersion)`) so the same drift is not reported twice; older vfox keeps the plugin's own warning from `.vfox-manifest`. - vfox unpacks a `.tar.xz` with Go's `archive/tar`, which stamps files with the time of the extraction and not with the time stored in the archive. The official `tar -xf` flow keeps those times, and `packages/flutter_tools/pubspec.lock` is newer than `pubspec.yaml` after it. After a vfox install the two share the time of the extraction, and whichever is written last looks newer, so `bin/internal/shared.sh` can find `pubspec.yaml` newer than `pubspec.lock` and rebuild the tool on the first run (`Building flutter tool...`). `manifest.touchPubspecLock` rewrites `pubspec.lock`, on every platform, to restore the order ([#37](https://github.com/version-fox/vfox-flutter/issues/37)). Source installs build the tool on the first run by design. - A Windows command line reaches `cmd.exe` as vfox 1.0.13 and later write it, unchanged ([vfox#712](https://github.com/version-fox/vfox/pull/712)), and older versions quote it again. `quote` in `lib/git.lua` and `lib/manifest.lua` puts double quotes around a path that contains whitespace, and leaves other paths bare, so that a path with a space works on 1.0.13 and a path without one still works on older versions. - `os.execute` reports success as `0` or as `true`, depending on the Lua it runs in, and `exec` in `lib/git.lua` accepts both. `io.popen` is how the plugin reads the output of `git` outside `Fingerprint` (the legacy drift check, the `git` commands of source installs); a command that prints nothing or fails reads as `nil`, which is why a missing `git` goes unnoticed in `lib/manifest.lua`. `Fingerprint` itself never uses `io.popen` or `os.execute`. diff --git a/docs/flutter-upgrade.md b/docs/flutter-upgrade.md index 72df194..3405912 100644 --- a/docs/flutter-upgrade.md +++ b/docs/flutter-upgrade.md @@ -29,8 +29,36 @@ If you already upgraded in place, restore the version with: vfox install --reinstall flutter@3.47.0 ``` -`vfox doctor` reports the same finding (`sdk.drift`), and a linked SDK that -changed reports it as a notice only: vfox does not own that SDK. +`vfox doctor` reports the same finding (`sdk.drift`). + +## An SDK installed by another manager + +A Flutter that is already on the machine, from Homebrew, mise, asdf, winget +or a manual install, can be used through vfox without downloading it again. +Register the directory that holds `bin` (anything else is refused, with the +reason): + +```bash +vfox link flutter@brew-3.47.4 +vfox use --global flutter@brew-3.47.4 +``` + +Google ships a full `.git` checkout in every release archive no matter who +downloads it, so the Fingerprint fact is the same `head`, and an in-place +change (for example `brew upgrade`) shows up the same way, with two +differences: vfox does not own that SDK, so the finding is an info-level +notice in `vfox doctor` only (`Found 0 errors, 0 warnings and 1 notice`), +and there is no `Fix:` line. `vfox install --reinstall` refuses a linked +version; upgrade or remove that SDK with its own manager, or run +`vfox uninstall flutter@` to remove just the link (the SDK itself is +left untouched). A linked directory without a `.git` records no fact and +stays silent, like an install without one. + +If the other manager's `flutter` keeps running instead of the one `vfox use` +selected, its directory sits earlier in `PATH`: `command -v flutter` shows +which one wins, and `vfox doctor` names the shadowing directory +(`path.shadowed`). What stays in front is decided by vfox's +[`path.mode`](https://vfox.dev/guides/configuration.html#path-order-settings). ## The warning diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index d1a7b3d..f2f6e26 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -166,7 +166,7 @@ Minutes later the same API answered in a second. Without a 429 a failing request - **A release you expect is missing from `vfox search`.** vfox keeps the result for 12 hours. `vfox config cache.availableHookDuration 0` turns the cache off. Flutter's index may not have it yet either, or your mirror's copy may not. - **`3.47.4` and `3.47.4-x64` are two installs.** On an x64 machine they are the same Flutter, see [versions.md](versions.md#installed-names). - **Uninstalling a version switched the global one.** vfox selects the first entry left in `vfox list flutter` when you uninstall the version in use, and that can be a beta. -- **`flutter` is a different Flutter than `vfox use` says.** Another Flutter earlier in your `PATH` wins, such as a manual install in `~/develop/flutter` or one from a package manager. `command -v flutter` shows which one runs, and its path should start with `~/.vfox/sdks/flutter/bin` or, in a project, `.vfox/sdks/flutter/bin`. A project's choice applies only in the directory that holds its `.vfox.toml`, not in the subdirectories, and vfox changes `PATH` when the prompt is shown, so `cd project && flutter run` on one line still runs the Flutter of the directory you came from, see [use-cases.md](use-cases.md#projects-on-different-flutter-versions). +- **`flutter` is a different Flutter than `vfox use` says.** Another Flutter earlier in your `PATH` wins, such as a manual install in `~/develop/flutter` or one from a package manager (Homebrew, mise, asdf, winget). `command -v flutter` shows which one runs, and its path should start with `~/.vfox/sdks/flutter/bin` or, in a project, `.vfox/sdks/flutter/bin`. To use that SDK through vfox instead, register it with `vfox link`, see [flutter-upgrade.md](flutter-upgrade.md#an-sdk-installed-by-another-manager). A project's choice applies only in the directory that holds its `.vfox.toml`, not in the subdirectories, and vfox changes `PATH` when the prompt is shown, so `cd project && flutter run` on one line still runs the Flutter of the directory you came from, see [use-cases.md](use-cases.md#projects-on-different-flutter-versions). - **Flutter says "A new version of Flutter is available!" and suggests `flutter upgrade`.** Ignore it: `flutter upgrade` moves the SDK under vfox, see [flutter-upgrade.md](flutter-upgrade.md). `vfox install flutter@stable` is the upgrade. `flutter --no-version-check` leaves the banner out. - **`FLUTTER_ROOT` is not set.** The plugin sets only `PATH`. The `flutter` script finds its own directory. - **`dart` is there without a Dart plugin.** The Flutter SDK includes the Dart SDK, and `dart` is in its `bin`. There is no need to add the [vfox-dart](https://github.com/version-fox/vfox-dart) plugin next to it. diff --git a/docs/zh-CN/changes.md b/docs/zh-CN/changes.md index 9cb69ce..3d4c9f9 100644 --- a/docs/zh-CN/changes.md +++ b/docs/zh-CN/changes.md @@ -6,7 +6,7 @@ ## 未发布 -- 漂移检查走 vfox 的 `Fingerprint` 钩子(需要 vfox 1.1.0 或更新的版本):插件只从文件读取 SDK 检出的 git HEAD 并报告,vfox 把它记在版本的收据里,`vfox use` 之后和 `vfox doctor` 里报告 `sdk.drift`,用 `vfox install --reinstall` 恢复。新版 vfox 上插件不再写 `.vfox-manifest`,也不再打印自己的警告,以免同一处漂移报两次;老于 1.1.0 的 vfox 保留旧的警告。见 [flutter-upgrade.md](flutter-upgrade.md)。 +- 漂移检查走 vfox 的 `Fingerprint` 钩子(需要 vfox 1.1.0 或更新的版本):插件只从文件读取 SDK 检出的 git HEAD 并报告,vfox 把它记在版本的收据里,`vfox use` 之后和 `vfox doctor` 里报告 `sdk.drift`,用 `vfox install --reinstall` 恢复。其他管理器(Homebrew、mise、asdf、winget、手动安装)装出来、登记给 vfox 的 SDK,只要还带着 `.git`,同样按 info 级别的提示覆盖(vfox 不拥有它)。新版 vfox 上插件不再写 `.vfox-manifest`,也不再打印自己的警告,以免同一处漂移报两次;老于 1.1.0 的 vfox 保留旧的警告。见 [flutter-upgrade.md](flutter-upgrade.md)。 ## 0.2.5 (2026-10-21) diff --git a/docs/zh-CN/development.md b/docs/zh-CN/development.md index e1f1bc4..9c4c4b0 100644 --- a/docs/zh-CN/development.md +++ b/docs/zh-CN/development.md @@ -43,7 +43,7 @@ vfox 加载 `metadata.lua`,在命令需要时调用 hook,并把 `PLUGIN` 和 - `PreInstall` 对解析不了的名字返回 `nil`,vfox 会把它报告成 `no installable runtime provided`。失败时它会抛出错误:`error()` 的内容会出现在 `plugin [PreInstall] method error:` 那一行里。 - 索引里有些版本不止列了一次。`hooks/available.lua` 里的 `newestPublications` 对一个版本的每个压缩包只保留最新(`release_date`)的那条,因为重新上传过的文件,只有最新那条的校验和才是对的(见 [troubleshooting.md](troubleshooting.md#checksum-error))。不同的版本绝不会合并,在两个渠道里的版本各有一个压缩包,两条都保留。`table.sort` 不是稳定排序,所以比较函数必须能区分任意两个条目,否则相等的条目出来的顺序取决于整个输入,而 `PreInstall` 取第一个匹配的。为此比较函数最后还比较版本和渠道。 - `PostInstall` 读取 `ctx.sdkInfo[PLUGIN.name]`。`pubspec.lock` 的修正放在 `pcall` 里,所以那里的失败永远不会让安装失败。旧的 `.vfox-manifest` 只在运行的 vfox 老于 1.1.0 时才写(`lib/util.lua` 里的 `supportsFingerprint`):新版 vfox 把 `Fingerprint` 事实记在版本的收据里。 -- `Fingerprint` 把 SDK 检出所在的提交作为 `facts.head` 报告,只从文件读 `.git/HEAD`(以及它指向的 ref 或 `packed-refs`):不跑进程,不访问网络,远快于 hook 要求的 50 毫秒。没有可检查的东西(没有 `.git`)时返回 nil,vfox 就保持安静。压缩包安装、源码安装和 OpenHarmony 构建版本都会报告。`PreUse` 在 vfox 1.1.0 及更新的版本上跳过自己的漂移检查(`supportsFingerprint(ctx.runtimeVersion)`),以免同一处漂移报两次;更老的 vfox 保留插件自己的 `.vfox-manifest` 警告。 +- `Fingerprint` 把 SDK 检出所在的提交作为 `facts.head` 报告,只从文件读 `.git/HEAD`(以及它指向的 ref 或 `packed-refs`):不跑进程,不访问网络,远快于 hook 要求的 50 毫秒。没有可检查的东西(没有 `.git`)时返回 nil,vfox 就保持安静。压缩包安装、源码安装和 OpenHarmony 构建版本都会报告,还带着 `.git` 的登记副本(Homebrew、mise、asdf、winget、手动安装)也一样。`PreUse` 在 vfox 1.1.0 及更新的版本上跳过自己的漂移检查(`supportsFingerprint(ctx.runtimeVersion)`),以免同一处漂移报两次;更老的 vfox 保留插件自己的 `.vfox-manifest` 警告。 - vfox 用 Go 的 `archive/tar` 解压 `.tar.xz`,它给文件打上的是解压时的时间,而不是压缩包里存的时间。官方的 `tar -xf` 流程会保留那些时间,于是 `packages/flutter_tools/pubspec.lock` 比 `pubspec.yaml` 新。vfox 安装之后,两者共用解压的时间,谁最后写入谁就显得更新,所以 `bin/internal/shared.sh` 可能发现 `pubspec.yaml` 比 `pubspec.lock` 新,在第一次运行时重新构建工具(`Building flutter tool...`)。`manifest.touchPubspecLock` 在所有平台上重写 `pubspec.lock`,把顺序恢复过来([#37](https://github.com/version-fox/vfox-flutter/issues/37))。源码安装按设计就要在第一次运行时构建工具。 - Windows 上的命令行,在 vfox 1.0.13 及更新的版本里原样交给 `cmd.exe`([vfox#712](https://github.com/version-fox/vfox/pull/712)),更老的版本会再加一层引号。`lib/git.lua` 和 `lib/manifest.lua` 里的 `quote` 只给含有空白字符的路径加双引号,其他路径保持原样,这样带空格的路径在 1.0.13 上可用,不带空格的路径在更老的版本上也依然可用。 - `os.execute` 报告成功的方式,视所用的 Lua 而定,可能是 `0`,也可能是 `true`,`lib/git.lua` 里的 `exec` 两者都接受。插件在 `Fingerprint` 之外读取 `git` 的输出靠的是 `io.popen`(旧的漂移检查、源码安装的 `git` 命令);没有输出或失败的命令读出来是 `nil`,所以 `lib/manifest.lua` 里缺少 `git` 时不会有任何察觉。`Fingerprint` 本身从不用 `io.popen` 或 `os.execute`。 diff --git a/docs/zh-CN/flutter-upgrade.md b/docs/zh-CN/flutter-upgrade.md index 102477e..d989b87 100644 --- a/docs/zh-CN/flutter-upgrade.md +++ b/docs/zh-CN/flutter-upgrade.md @@ -21,7 +21,20 @@ vfox use --global flutter@3.47.4 vfox install --reinstall flutter@3.47.0 ``` -`vfox doctor` 会报告同一个问题(`sdk.drift`)。通过 `vfox link` 登记的 SDK 变了,只会作为提示出现:vfox 并不拥有那个 SDK。 +`vfox doctor` 会报告同一个问题(`sdk.drift`)。 + +## 用其他包管理器装的 SDK + +机器上已有的 Flutter,不管是 Homebrew、mise、asdf、winget 装的,还是手动装的,都可以登记给 vfox 用,不用重新下载。登记持有 `bin` 的那个目录(不是的会被拒绝,并说明原因): + +```bash +vfox link flutter@brew-3.47.4 +vfox use --global flutter@brew-3.47.4 +``` + +不管是谁下载的,Google 每个发布压缩包里都带有完整的 `.git` 检出,所以 Fingerprint 事实还是同一个 `head`,就地改动(比如 `brew upgrade`)也会同样报出来,有两点不同:vfox 并不拥有那个 SDK,所以这条问题只是 `vfox doctor` 里 info 级别的提示(`Found 0 errors, 0 warnings and 1 notice`),也没有 `Fix:` 那一行。`vfox install --reinstall` 会拒绝登记来的版本;要用它自己的管理器去升级或删除那个 SDK,或者执行 `vfox uninstall flutter@<名字>` 只删掉登记(SDK 本身原样保留)。没有 `.git` 的登记目录记不下事实,和没有 `.git` 的安装一样,永远安静。 + +如果另一个管理器的 `flutter` 一直在运行,选中的 `vfox use` 版本始终轮不到它,说明它的目录在 `PATH` 里更靠前:`command -v flutter` 能看到实际赢的是哪一个,`vfox doctor` 会点出挡在前面的目录(`path.shadowed`)。哪些目录留在前面,由 vfox 的 [`path.mode`](https://vfox.dev/zh-hans/guides/configuration.html#path-order-settings) 决定。 ## 警告内容 diff --git a/docs/zh-CN/troubleshooting.md b/docs/zh-CN/troubleshooting.md index 0b87b27..78d7ea8 100644 --- a/docs/zh-CN/troubleshooting.md +++ b/docs/zh-CN/troubleshooting.md @@ -166,7 +166,7 @@ gitcode.com 限制匿名客户端的请求次数。超出限制时它回答 HTTP - **预期的版本在 `vfox search` 里没有。** vfox 会把结果缓存 12 小时。`vfox config cache.availableHookDuration 0` 可以关掉缓存。也可能是 Flutter 的索引里还没有它,或者你的镜像那份里还没有。 - **`3.47.4` 和 `3.47.4-x64` 是两份安装。** 在 x64 机器上它们是同一个 Flutter,见 [versions.md](versions.md#已安装的名称)。 - **卸载一个版本后,全局版本被换掉了。** 卸载正在使用的版本时,vfox 会选 `vfox list flutter` 里剩下的第一项,那可能是个 beta。 -- **`flutter` 运行的不是 `vfox use` 选的那个 Flutter。** `PATH` 里更靠前的另一个 Flutter 会胜出,比如手动装在 `~/develop/flutter` 的,或者包管理器装的。`command -v flutter` 能看到实际运行的是哪一个,它的路径应当以 `~/.vfox/sdks/flutter/bin` 开头,在项目里则是 `.vfox/sdks/flutter/bin`。项目里的选择只在 `.vfox.toml` 所在的目录生效,子目录里不生效;vfox 又是在提示符出现时才改 `PATH`,所以把 `cd project && flutter run` 写在一行里,运行的还是上一个目录的 Flutter,见 [use-cases.md](use-cases.md#项目用不同的-flutter-版本)。 +- **`flutter` 运行的不是 `vfox use` 选的那个 Flutter。** `PATH` 里更靠前的另一个 Flutter 会胜出,比如手动装在 `~/develop/flutter` 的,或者包管理器(Homebrew、mise、asdf、winget)装的。`command -v flutter` 能看到实际运行的是哪一个,它的路径应当以 `~/.vfox/sdks/flutter/bin` 开头,在项目里则是 `.vfox/sdks/flutter/bin`。想让那个 SDK 走 vfox 用,用 `vfox link` 把它登记进来,见 [flutter-upgrade.md](flutter-upgrade.md#用其他包管理器装的-sdk)。项目里的选择只在 `.vfox.toml` 所在的目录生效,子目录里不生效;vfox 又是在提示符出现时才改 `PATH`,所以把 `cd project && flutter run` 写在一行里,运行的还是上一个目录的 Flutter,见 [use-cases.md](use-cases.md#项目用不同的-flutter-版本)。 - **Flutter 说“A new version of Flutter is available!”并建议执行 `flutter upgrade`。** 别理它:`flutter upgrade` 会在 vfox 的背后改动 SDK,见 [flutter-upgrade.md](flutter-upgrade.md)。`vfox install flutter@stable` 才是升级。`flutter --no-version-check` 可以不显示这条提示。 - **`FLUTTER_ROOT` 没有设置。** 插件只设置 `PATH`。`flutter` 脚本会自己找到它所在的目录。 - **没有装 Dart 插件,`dart` 却在。** Flutter SDK 包含 Dart SDK,`dart` 就在它的 `bin` 里。不需要再另外添加 [vfox-dart](https://github.com/version-fox/vfox-dart) 插件。 From 2cf357a1bffb3a6b5f75a20d22a3b6a2ecaca0d7 Mon Sep 17 00:00:00 2001 From: Qiheng He Date: Tue, 10 Nov 2026 11:43:53 +0800 Subject: [PATCH 4/4] feat: add Detect hook for vfox link --detect flutter Scan well-known install locations (Homebrew Caskroom, mise, asdf, FVM, manual dirs, C:/src/flutter on Windows) for SDKs whose bin holds flutter and whose root version file names a linkable version. vfox skips what is already installed or linked. lib/detect_sdk.lua (not detect.lua: vfox searches hooks/ before lib/, so require("detect") would loop on hooks/detect.lua). Cover with offline hook tests; verified end to end against vfox 1.1.0 (detect, link, receipt, doctor notice, skip on rerun). Docs are detect-first with manual link as fallback. --- docs/changes.md | 3 +- docs/development.md | 9 +- docs/flutter-upgrade.md | 18 ++- docs/troubleshooting.md | 2 +- docs/zh-CN/changes.md | 3 +- docs/zh-CN/development.md | 9 +- docs/zh-CN/flutter-upgrade.md | 9 +- docs/zh-CN/troubleshooting.md | 2 +- hooks/detect.lua | 23 +++ lib/detect_sdk.lua | 256 ++++++++++++++++++++++++++++++++++ tests/hooks_test.lua | 107 ++++++++++++++ 11 files changed, 426 insertions(+), 15 deletions(-) create mode 100644 hooks/detect.lua create mode 100644 lib/detect_sdk.lua diff --git a/docs/changes.md b/docs/changes.md index a14a1fd..8d6163b 100644 --- a/docs/changes.md +++ b/docs/changes.md @@ -6,7 +6,8 @@ What changed in each release, as a user notices it. GitHub's release pages and t ## Unreleased -- Drift detection goes through vfox's `Fingerprint` hook (needs vfox 1.1.0 or later): the plugin reports the SDK checkout's git HEAD from files only, vfox records it in the version's receipt and reports `sdk.drift` after `vfox use` and in `vfox doctor`, fixed with `vfox install --reinstall`. Linked copies from other managers (Homebrew, mise, asdf, winget, manual installs) are covered the same way when they still carry their `.git`, as an info-level notice that vfox does not own. The plugin no longer writes `.vfox-manifest` on new vfox and no longer prints its own warning there, so the same drift is not reported twice; vfox older than 1.1.0 keeps the old warning. See [flutter-upgrade.md](flutter-upgrade.md). +- Drift detection goes through vfox's `Fingerprint` hook (needs vfox 1.1.0 or later): the plugin reports the SDK checkout's git HEAD from files only, vfox records it in the version's receipt and reports `sdk.drift` after `vfox use` and in `vfox doctor`, fixed with `vfox install --reinstall`. Linked copies from other managers (Homebrew, mise, asdf, FVM, manual installs) are covered the same way when they still carry their `.git`, as an info-level notice that vfox does not own. The plugin no longer writes `.vfox-manifest` on new vfox and no longer prints its own warning there, so the same drift is not reported twice; vfox older than 1.1.0 keeps the old warning. See [flutter-upgrade.md](flutter-upgrade.md). +- `vfox link --detect flutter` finds the Flutter SDKs that are already on the machine, from Homebrew, mise, asdf, FVM and manual installs in their usual places, and links what it finds (needs vfox 1.1.0 or later). Anything elsewhere is for `vfox link flutter@ `. ## 0.2.5 (2026-10-21) diff --git a/docs/development.md b/docs/development.md index ebe4d54..b16d44c 100644 --- a/docs/development.md +++ b/docs/development.md @@ -10,12 +10,14 @@ hooks/available.lua vfox search: the list of every name hooks/pre_install.lua vfox install: resolve a name to a package; and PostInstall hooks/pre_use.lua vfox use: the drift check for vfox older than 1.1.0 hooks/fingerprint.lua vfox use / doctor on vfox 1.1.0+: the git HEAD fact +hooks/detect.lua vfox link --detect on vfox 1.1.0+: find SDKs already on the machine hooks/env_keys.lua PATH lib/util.lua the mirror, the platform, version names, their order, and the vfox version gate lib/git.lua git commands, the GitHub mirror, the work directory lib/source.lua source installs on Linux ARM64 and Windows ARM64 lib/ohos.lua OpenHarmony releases and checkouts lib/manifest.lua the Fingerprint HEAD reader, the legacy `.vfox-manifest`, and the pubspec.lock fix +lib/detect_sdk.lua the well-known install locations and SDK identification for Detect tests/hooks_test.lua offline hook tests tests/e2e/ container tests, see e2e.md Injection.lua type hints for what vfox injects, never loaded @@ -43,10 +45,11 @@ vfox loads `metadata.lua`, calls a hook when a command needs it, and puts `PLUGI - `PreInstall` returns `nil` for a name it cannot resolve, which vfox reports as `no installable runtime provided`. It raises an error for a failure: the message of `error()` shows up in the `plugin [PreInstall] method error:` line. - The index lists some releases more than once. `newestPublications` in `hooks/available.lua` keeps the newest entry (`release_date`) of each archive of a version, because a file that was uploaded again has the checksum of the newest entry only (see [troubleshooting.md](troubleshooting.md#checksum-error)). Different versions never merge, and a release in two channels has an archive in each and keeps both. `table.sort` is not stable, so the comparator has to tell any two entries apart, or equal entries come out in an order that depends on the whole input, and `PreInstall` takes the first match. It ends with the version and the channel for that. - `PostInstall` reads `ctx.sdkInfo[PLUGIN.name]`. It runs the `pubspec.lock` fix under `pcall`, so a failure there never fails the install. The legacy `.vfox-manifest` is only written when the running vfox is older than 1.1.0 (`supportsFingerprint` in `lib/util.lua`): newer vfox records the `Fingerprint` fact in the version's receipt instead. -- `Fingerprint` reports the commit the SDK checkout is at as `facts.head`, by reading `.git/HEAD` (and the ref or `packed-refs` it points to) from files only: no processes, no network, well under the 50 ms the hook must keep. It returns nil when there is nothing to check (no `.git`), and vfox stays silent then. Archive installs, source installs and OpenHarmony builds all report it, as do linked copies that still carry their `.git` (Homebrew, mise, asdf, winget, manual installs). `PreUse` skips its own drift check on vfox 1.1.0+ (`supportsFingerprint(ctx.runtimeVersion)`) so the same drift is not reported twice; older vfox keeps the plugin's own warning from `.vfox-manifest`. +- `Fingerprint` reports the commit the SDK checkout is at as `facts.head`, by reading `.git/HEAD` (and the ref or `packed-refs` it points to) from files only: no processes, no network, well under the 50 ms the hook must keep. It returns nil when there is nothing to check (no `.git`), and vfox stays silent then. Archive installs, source installs and OpenHarmony builds all report it, as do linked copies that still carry their `.git` (Homebrew, mise, asdf, FVM, manual installs). `PreUse` skips its own drift check on vfox 1.1.0+ (`supportsFingerprint(ctx.runtimeVersion)`) so the same drift is not reported twice; older vfox keeps the plugin's own warning from `.vfox-manifest`. +- `Detect` scans the well-known install locations for `vfox link --detect`: Homebrew's Caskroom (macOS), the install directories of mise (`$MISE_DATA_DIR`, else `~/.local/share/mise`) and asdf (`$ASDF_DATA_DIR`, else `~/.asdf`), FVM's versions, and a few manual-install directories (plus `C:\src\flutter` on Windows). A candidate is an SDK when its `bin` holds `flutter` (or `flutter.bat`) and its root `version` file names a version vfox could link under; the note says where it was found. `lib` modules must not share a hook's filename: vfox searches `hooks/` before `lib/`, so `require("detect")` would load `hooks/detect.lua` and loop, which is why the module lives in `lib/detect_sdk.lua`. - vfox unpacks a `.tar.xz` with Go's `archive/tar`, which stamps files with the time of the extraction and not with the time stored in the archive. The official `tar -xf` flow keeps those times, and `packages/flutter_tools/pubspec.lock` is newer than `pubspec.yaml` after it. After a vfox install the two share the time of the extraction, and whichever is written last looks newer, so `bin/internal/shared.sh` can find `pubspec.yaml` newer than `pubspec.lock` and rebuild the tool on the first run (`Building flutter tool...`). `manifest.touchPubspecLock` rewrites `pubspec.lock`, on every platform, to restore the order ([#37](https://github.com/version-fox/vfox-flutter/issues/37)). Source installs build the tool on the first run by design. - A Windows command line reaches `cmd.exe` as vfox 1.0.13 and later write it, unchanged ([vfox#712](https://github.com/version-fox/vfox/pull/712)), and older versions quote it again. `quote` in `lib/git.lua` and `lib/manifest.lua` puts double quotes around a path that contains whitespace, and leaves other paths bare, so that a path with a space works on 1.0.13 and a path without one still works on older versions. -- `os.execute` reports success as `0` or as `true`, depending on the Lua it runs in, and `exec` in `lib/git.lua` accepts both. `io.popen` is how the plugin reads the output of `git` outside `Fingerprint` (the legacy drift check, the `git` commands of source installs); a command that prints nothing or fails reads as `nil`, which is why a missing `git` goes unnoticed in `lib/manifest.lua`. `Fingerprint` itself never uses `io.popen` or `os.execute`. +- `os.execute` reports success as `0` or as `true`, depending on the Lua it runs in, and `exec` in `lib/git.lua` accepts both. `io.popen` is how the plugin reads the output of `git` outside `Fingerprint` (the legacy drift check, the `git` commands of source installs) and how `Detect` lists install directories; a command that prints nothing or fails reads as `nil`, which is why a missing `git` goes unnoticed in `lib/manifest.lua`. `Fingerprint` itself never uses `io.popen` or `os.execute`. - `lib/git.lua` takes the work directory from `VFOX_HOME`, then `HOME`, then `USERPROFILE`, and appends `.vfox/tmp/`. With `VFOX_HOME` set that is `$VFOX_HOME/.vfox/tmp/`, one `.vfox` below the vfox home. The directory is not removed when the install fails. - `git` runs with your configuration, except for two settings that `git.init` writes into the checkout: `core.longpaths=true`, and `core.autocrlf=false`, because a global `true` writes Flutter's shell scripts with CRLF (see [arm64.md](arm64.md#limits)). On Windows `false` writes the same CRLF files `true` does, since `core.eol` is native there. That is how git works, and it was checked on Linux with `core.eol=crlf` and Flutter's `.gitattributes`, which starts with `* text=auto`: the same files came out CRLF for both settings, and `bin/flutter` stayed LF. The Windows ARM64 container tests install from a checkout like this one. Fetches get `http.lowSpeedLimit=1000` and `http.lowSpeedTime=60`, which `GIT_HTTP_LOW_SPEED_LIMIT` and `GIT_HTTP_LOW_SPEED_TIME` override. - `lib/ohos.lua` waits for gitcode.com in two ways. Installing a build needs the releases, and makes five attempts: 10 seconds apart, and 30, 60, 120 and 180 seconds after HTTP 429. Listing them is a courtesy to `vfox search`, so `ohos.list()` makes two attempts 2 seconds apart, stops at HTTP 429, and returns `nil` and the reason. `Available` then writes one warning line to stderr and lists the official releases. @@ -108,7 +111,7 @@ Run it from the repository root. The test stubs `http`, `json` and `os.getenv`, - a checkout does not take `core.autocrlf` from your git configuration (this one runs real `git`, and skips itself without it); - an unsupported CPU is named in the message. -The `Fingerprint` file reader and the `PreUse` version gate are not in this file either. The container tests cover the drift end to end, see [e2e.md](e2e.md). Lint, license headers and the container tests are in [e2e.md](e2e.md#local-checks). +The `Fingerprint` file reader and the `PreUse` version gate are not in this file either; `Detect` is (manager layouts, version-file naming, and the Windows listing). The container tests cover the drift end to end, see [e2e.md](e2e.md). Lint, license headers and the container tests are in [e2e.md](e2e.md#local-checks). To call a single hook, vfox 1.0.13 and later has `vfox plugin run`. It does not register the plugin, and `--os` and `--arch` answer for another platform: diff --git a/docs/flutter-upgrade.md b/docs/flutter-upgrade.md index 3405912..71ded95 100644 --- a/docs/flutter-upgrade.md +++ b/docs/flutter-upgrade.md @@ -33,10 +33,20 @@ vfox install --reinstall flutter@3.47.0 ## An SDK installed by another manager -A Flutter that is already on the machine, from Homebrew, mise, asdf, winget -or a manual install, can be used through vfox without downloading it again. -Register the directory that holds `bin` (anything else is refused, with the -reason): +A Flutter that is already on this machine, from Homebrew, mise, asdf, FVM or +a manual install, can be used through vfox without downloading it again. +Let vfox find it: + +```bash +vfox link --detect flutter +vfox use --global flutter@3.47.4 +``` + +`--detect` looks in the usual places (Homebrew's Caskroom, the install +directories of mise and asdf, FVM's versions, a few manual-install locations) +and links what it finds. What is already installed or linked is skipped, +with the reason. Anything elsewhere is for the manual form, with the +directory that holds `bin`: ```bash vfox link flutter@brew-3.47.4 diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index f2f6e26..17c23f5 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -166,7 +166,7 @@ Minutes later the same API answered in a second. Without a 429 a failing request - **A release you expect is missing from `vfox search`.** vfox keeps the result for 12 hours. `vfox config cache.availableHookDuration 0` turns the cache off. Flutter's index may not have it yet either, or your mirror's copy may not. - **`3.47.4` and `3.47.4-x64` are two installs.** On an x64 machine they are the same Flutter, see [versions.md](versions.md#installed-names). - **Uninstalling a version switched the global one.** vfox selects the first entry left in `vfox list flutter` when you uninstall the version in use, and that can be a beta. -- **`flutter` is a different Flutter than `vfox use` says.** Another Flutter earlier in your `PATH` wins, such as a manual install in `~/develop/flutter` or one from a package manager (Homebrew, mise, asdf, winget). `command -v flutter` shows which one runs, and its path should start with `~/.vfox/sdks/flutter/bin` or, in a project, `.vfox/sdks/flutter/bin`. To use that SDK through vfox instead, register it with `vfox link`, see [flutter-upgrade.md](flutter-upgrade.md#an-sdk-installed-by-another-manager). A project's choice applies only in the directory that holds its `.vfox.toml`, not in the subdirectories, and vfox changes `PATH` when the prompt is shown, so `cd project && flutter run` on one line still runs the Flutter of the directory you came from, see [use-cases.md](use-cases.md#projects-on-different-flutter-versions). +- **`flutter` is a different Flutter than `vfox use` says.** Another Flutter earlier in your `PATH` wins, such as a manual install in `~/develop/flutter` or one from a package manager (Homebrew, mise, asdf, FVM). `command -v flutter` shows which one runs, and its path should start with `~/.vfox/sdks/flutter/bin` or, in a project, `.vfox/sdks/flutter/bin`. To use that SDK through vfox instead, run `vfox link --detect flutter` (or `vfox link flutter@ ` for a custom location), see [flutter-upgrade.md](flutter-upgrade.md#an-sdk-installed-by-another-manager). A project's choice applies only in the directory that holds its `.vfox.toml`, not in the subdirectories, and vfox changes `PATH` when the prompt is shown, so `cd project && flutter run` on one line still runs the Flutter of the directory you came from, see [use-cases.md](use-cases.md#projects-on-different-flutter-versions). - **Flutter says "A new version of Flutter is available!" and suggests `flutter upgrade`.** Ignore it: `flutter upgrade` moves the SDK under vfox, see [flutter-upgrade.md](flutter-upgrade.md). `vfox install flutter@stable` is the upgrade. `flutter --no-version-check` leaves the banner out. - **`FLUTTER_ROOT` is not set.** The plugin sets only `PATH`. The `flutter` script finds its own directory. - **`dart` is there without a Dart plugin.** The Flutter SDK includes the Dart SDK, and `dart` is in its `bin`. There is no need to add the [vfox-dart](https://github.com/version-fox/vfox-dart) plugin next to it. diff --git a/docs/zh-CN/changes.md b/docs/zh-CN/changes.md index 3d4c9f9..9f66daa 100644 --- a/docs/zh-CN/changes.md +++ b/docs/zh-CN/changes.md @@ -6,7 +6,8 @@ ## 未发布 -- 漂移检查走 vfox 的 `Fingerprint` 钩子(需要 vfox 1.1.0 或更新的版本):插件只从文件读取 SDK 检出的 git HEAD 并报告,vfox 把它记在版本的收据里,`vfox use` 之后和 `vfox doctor` 里报告 `sdk.drift`,用 `vfox install --reinstall` 恢复。其他管理器(Homebrew、mise、asdf、winget、手动安装)装出来、登记给 vfox 的 SDK,只要还带着 `.git`,同样按 info 级别的提示覆盖(vfox 不拥有它)。新版 vfox 上插件不再写 `.vfox-manifest`,也不再打印自己的警告,以免同一处漂移报两次;老于 1.1.0 的 vfox 保留旧的警告。见 [flutter-upgrade.md](flutter-upgrade.md)。 +- 漂移检查走 vfox 的 `Fingerprint` 钩子(需要 vfox 1.1.0 或更新的版本):插件只从文件读取 SDK 检出的 git HEAD 并报告,vfox 把它记在版本的收据里,`vfox use` 之后和 `vfox doctor` 里报告 `sdk.drift`,用 `vfox install --reinstall` 恢复。其他管理器(Homebrew、mise、asdf、FVM、手动安装)装出来、登记给 vfox 的 SDK,只要还带着 `.git`,同样按 info 级别的提示覆盖(vfox 不拥有它)。新版 vfox 上插件不再写 `.vfox-manifest`,也不再打印自己的警告,以免同一处漂移报两次;老于 1.1.0 的 vfox 保留旧的警告。见 [flutter-upgrade.md](flutter-upgrade.md)。 +- `vfox link --detect flutter` 会找出机器上已有的 Flutter SDK(Homebrew、mise、asdf、FVM 和手动安装在惯常位置的),找到就登记(需要 vfox 1.1.0 或更新的版本)。不在这些地方的,用 `vfox link flutter@<名字> <路径>`。 ## 0.2.5 (2026-10-21) diff --git a/docs/zh-CN/development.md b/docs/zh-CN/development.md index 9c4c4b0..0c5a55f 100644 --- a/docs/zh-CN/development.md +++ b/docs/zh-CN/development.md @@ -10,12 +10,14 @@ hooks/available.lua vfox search:所有名字的列表 hooks/pre_install.lua vfox install:把名字解析成一个包;还有 PostInstall hooks/pre_use.lua vfox use:vfox 老于 1.1.0 时的漂移检查 hooks/fingerprint.lua vfox 1.1.0 及更新的版本上,`vfox use` / `doctor` 用的 git HEAD 事实 +hooks/detect.lua vfox 1.1.0 及更新的版本上,`vfox link --detect` 找机器上已有的 SDK hooks/env_keys.lua PATH lib/util.lua 镜像、平台、版本名及其顺序,还有 vfox 版本的判断 lib/git.lua git 命令、GitHub 镜像、工作目录 lib/source.lua Linux ARM64 和 Windows ARM64 的源码安装 lib/ohos.lua OpenHarmony 发布版本和检出 lib/manifest.lua Fingerprint 的 HEAD 读取、旧的 `.vfox-manifest`,以及 pubspec.lock 的修正 +lib/detect_sdk.lua 给 Detect 用的知名安装位置和 SDK 判定 tests/hooks_test.lua 离线的 hook 测试 tests/e2e/ 容器测试,见 e2e.md Injection.lua vfox 注入内容的类型提示,从不加载 @@ -43,10 +45,11 @@ vfox 加载 `metadata.lua`,在命令需要时调用 hook,并把 `PLUGIN` 和 - `PreInstall` 对解析不了的名字返回 `nil`,vfox 会把它报告成 `no installable runtime provided`。失败时它会抛出错误:`error()` 的内容会出现在 `plugin [PreInstall] method error:` 那一行里。 - 索引里有些版本不止列了一次。`hooks/available.lua` 里的 `newestPublications` 对一个版本的每个压缩包只保留最新(`release_date`)的那条,因为重新上传过的文件,只有最新那条的校验和才是对的(见 [troubleshooting.md](troubleshooting.md#checksum-error))。不同的版本绝不会合并,在两个渠道里的版本各有一个压缩包,两条都保留。`table.sort` 不是稳定排序,所以比较函数必须能区分任意两个条目,否则相等的条目出来的顺序取决于整个输入,而 `PreInstall` 取第一个匹配的。为此比较函数最后还比较版本和渠道。 - `PostInstall` 读取 `ctx.sdkInfo[PLUGIN.name]`。`pubspec.lock` 的修正放在 `pcall` 里,所以那里的失败永远不会让安装失败。旧的 `.vfox-manifest` 只在运行的 vfox 老于 1.1.0 时才写(`lib/util.lua` 里的 `supportsFingerprint`):新版 vfox 把 `Fingerprint` 事实记在版本的收据里。 -- `Fingerprint` 把 SDK 检出所在的提交作为 `facts.head` 报告,只从文件读 `.git/HEAD`(以及它指向的 ref 或 `packed-refs`):不跑进程,不访问网络,远快于 hook 要求的 50 毫秒。没有可检查的东西(没有 `.git`)时返回 nil,vfox 就保持安静。压缩包安装、源码安装和 OpenHarmony 构建版本都会报告,还带着 `.git` 的登记副本(Homebrew、mise、asdf、winget、手动安装)也一样。`PreUse` 在 vfox 1.1.0 及更新的版本上跳过自己的漂移检查(`supportsFingerprint(ctx.runtimeVersion)`),以免同一处漂移报两次;更老的 vfox 保留插件自己的 `.vfox-manifest` 警告。 +- `Fingerprint` 把 SDK 检出所在的提交作为 `facts.head` 报告,只从文件读 `.git/HEAD`(以及它指向的 ref 或 `packed-refs`):不跑进程,不访问网络,远快于 hook 要求的 50 毫秒。没有可检查的东西(没有 `.git`)时返回 nil,vfox 就保持安静。压缩包安装、源码安装和 OpenHarmony 构建版本都会报告,还带着 `.git` 的登记副本(Homebrew、mise、asdf、FVM、手动安装)也一样。`PreUse` 在 vfox 1.1.0 及更新的版本上跳过自己的漂移检查(`supportsFingerprint(ctx.runtimeVersion)`),以免同一处漂移报两次;更老的 vfox 保留插件自己的 `.vfox-manifest` 警告。 +- `Detect` 给 `vfox link --detect` 扫描那些人都知道的安装位置:macOS 上 Homebrew 的 Caskroom、mise(`$MISE_DATA_DIR`,否则 `~/.local/share/mise`)和 asdf(`$ASDF_DATA_DIR`,否则 `~/.asdf`)的安装目录、FVM 的 versions,以及几个手动安装的目录(Windows 上还有 `C:\src\flutter`)。`bin` 里有 `flutter`(或 `flutter.bat`)、根目录 `version` 文件写着 vfox 能拿来登记的名字,才算一个 SDK,备注里写它是在哪里找到的。`lib` 里的模块不能和 hook 同名:vfox 先搜 `hooks/` 再搜 `lib/`,所以 `require("detect")` 会载入 `hooks/detect.lua` 自己,造成循环,这就是模块放在 `lib/detect_sdk.lua` 的原因。 - vfox 用 Go 的 `archive/tar` 解压 `.tar.xz`,它给文件打上的是解压时的时间,而不是压缩包里存的时间。官方的 `tar -xf` 流程会保留那些时间,于是 `packages/flutter_tools/pubspec.lock` 比 `pubspec.yaml` 新。vfox 安装之后,两者共用解压的时间,谁最后写入谁就显得更新,所以 `bin/internal/shared.sh` 可能发现 `pubspec.yaml` 比 `pubspec.lock` 新,在第一次运行时重新构建工具(`Building flutter tool...`)。`manifest.touchPubspecLock` 在所有平台上重写 `pubspec.lock`,把顺序恢复过来([#37](https://github.com/version-fox/vfox-flutter/issues/37))。源码安装按设计就要在第一次运行时构建工具。 - Windows 上的命令行,在 vfox 1.0.13 及更新的版本里原样交给 `cmd.exe`([vfox#712](https://github.com/version-fox/vfox/pull/712)),更老的版本会再加一层引号。`lib/git.lua` 和 `lib/manifest.lua` 里的 `quote` 只给含有空白字符的路径加双引号,其他路径保持原样,这样带空格的路径在 1.0.13 上可用,不带空格的路径在更老的版本上也依然可用。 -- `os.execute` 报告成功的方式,视所用的 Lua 而定,可能是 `0`,也可能是 `true`,`lib/git.lua` 里的 `exec` 两者都接受。插件在 `Fingerprint` 之外读取 `git` 的输出靠的是 `io.popen`(旧的漂移检查、源码安装的 `git` 命令);没有输出或失败的命令读出来是 `nil`,所以 `lib/manifest.lua` 里缺少 `git` 时不会有任何察觉。`Fingerprint` 本身从不用 `io.popen` 或 `os.execute`。 +- `os.execute` 报告成功的方式,视所用的 Lua 而定,可能是 `0`,也可能是 `true`,`lib/git.lua` 里的 `exec` 两者都接受。插件在 `Fingerprint` 之外读取 `git` 的输出靠的是 `io.popen`(旧的漂移检查、源码安装的 `git` 命令),`Detect` 列安装目录也靠它;没有输出或失败的命令读出来是 `nil`,所以 `lib/manifest.lua` 里缺少 `git` 时不会有任何察觉。`Fingerprint` 本身从不用 `io.popen` 或 `os.execute`。 - `lib/git.lua` 的工作目录依次取自 `VFOX_HOME`、`HOME`、`USERPROFILE`,再加上 `.vfox/tmp/<名称>`。设置了 `VFOX_HOME` 时就是 `$VFOX_HOME/.vfox/tmp/<名称>`,比 vfox 主目录低一层 `.vfox`。安装失败时这个目录不会被删除。 - `git` 用的是你的配置,只有 `git.init` 写进检出里的两项设置例外:`core.longpaths=true`,以及 `core.autocrlf=false`,因为全局的 `true` 会让 Flutter 的 shell 脚本带上 CRLF(见 [arm64.md](arm64.md#限制))。在 Windows 上 `false` 写出的 CRLF 文件和 `true` 一样,因为那里的 `core.eol` 是 native。这是 git 本身的工作方式,我们在 Linux 上用 `core.eol=crlf` 和 Flutter 的 `.gitattributes`(第一条是 `* text=auto`)检查过:两种设置写出的文件同样是 CRLF,`bin/flutter` 则保持 LF。Windows ARM64 的容器测试装的就是这样的检出。拉取时会加上 `http.lowSpeedLimit=1000` 和 `http.lowSpeedTime=60`,`GIT_HTTP_LOW_SPEED_LIMIT` 和 `GIT_HTTP_LOW_SPEED_TIME` 可以覆盖它们。 - `lib/ohos.lua` 等 gitcode.com 有两种方式。安装构建版本需要发布版本列表,所以尝试五次:间隔 10 秒,遇到 HTTP 429 之后是 30、60、120 和 180 秒。列出它们只是给 `vfox search` 帮个忙,所以 `ohos.list()` 只尝试两次,间隔 2 秒,遇到 HTTP 429 就停,并返回 `nil` 和原因。然后 `Available` 往 stderr 写一行警告,再列出官方版本。 @@ -108,7 +111,7 @@ go run github.com/yuin/gopher-lua/cmd/glua@v1.1.1 tests/hooks_test.lua - 检出不会采用你 git 配置里的 `core.autocrlf`(这一项运行真正的 `git`,没有它就跳过); - 不支持的 CPU 会在提示里点出名字。 -`Fingerprint` 的文件读取和 `PreUse` 的版本判断不在这个文件里,源码安装和 OpenHarmony 构建版本也只测到它们的 `git` 命令为止。这些由容器测试覆盖,见 [e2e.md](e2e.md)。lint、许可证头和容器测试见 [e2e.md](e2e.md#本地检查)。 +`Fingerprint` 的文件读取和 `PreUse` 的版本判断不在这个文件里,`Detect` 在(管理器布局、版本文件命名,以及 Windows 的目录列出)。源码安装和 OpenHarmony 构建版本也只测到它们的 `git` 命令为止。这些由容器测试覆盖,见 [e2e.md](e2e.md)。lint、许可证头和容器测试见 [e2e.md](e2e.md#本地检查)。 要单独调用一个 hook,vfox 1.0.13 及更新的版本有 `vfox plugin run`。它不会注册插件,`--os` 和 `--arch` 可以替另一个平台作答: diff --git a/docs/zh-CN/flutter-upgrade.md b/docs/zh-CN/flutter-upgrade.md index d989b87..ef65549 100644 --- a/docs/zh-CN/flutter-upgrade.md +++ b/docs/zh-CN/flutter-upgrade.md @@ -25,7 +25,14 @@ vfox install --reinstall flutter@3.47.0 ## 用其他包管理器装的 SDK -机器上已有的 Flutter,不管是 Homebrew、mise、asdf、winget 装的,还是手动装的,都可以登记给 vfox 用,不用重新下载。登记持有 `bin` 的那个目录(不是的会被拒绝,并说明原因): +机器上已有的 Flutter,不管是 Homebrew、mise、asdf、FVM 装的,还是手动装的,都可以登记给 vfox 用,不用重新下载。先让 vfox 自己找: + +```bash +vfox link --detect flutter +vfox use --global flutter@3.47.4 +``` + +`--detect` 会看那些惯常的位置(Homebrew 的 Caskroom、mise 和 asdf 的安装目录、FVM 的 versions、几个手动安装的常用目录),找到就登记。已经装过或登记过的会跳过,并说明原因。不在这些地方的,用手动的形式,登记持有 `bin` 的那个目录: ```bash vfox link flutter@brew-3.47.4 diff --git a/docs/zh-CN/troubleshooting.md b/docs/zh-CN/troubleshooting.md index 78d7ea8..d192de0 100644 --- a/docs/zh-CN/troubleshooting.md +++ b/docs/zh-CN/troubleshooting.md @@ -166,7 +166,7 @@ gitcode.com 限制匿名客户端的请求次数。超出限制时它回答 HTTP - **预期的版本在 `vfox search` 里没有。** vfox 会把结果缓存 12 小时。`vfox config cache.availableHookDuration 0` 可以关掉缓存。也可能是 Flutter 的索引里还没有它,或者你的镜像那份里还没有。 - **`3.47.4` 和 `3.47.4-x64` 是两份安装。** 在 x64 机器上它们是同一个 Flutter,见 [versions.md](versions.md#已安装的名称)。 - **卸载一个版本后,全局版本被换掉了。** 卸载正在使用的版本时,vfox 会选 `vfox list flutter` 里剩下的第一项,那可能是个 beta。 -- **`flutter` 运行的不是 `vfox use` 选的那个 Flutter。** `PATH` 里更靠前的另一个 Flutter 会胜出,比如手动装在 `~/develop/flutter` 的,或者包管理器(Homebrew、mise、asdf、winget)装的。`command -v flutter` 能看到实际运行的是哪一个,它的路径应当以 `~/.vfox/sdks/flutter/bin` 开头,在项目里则是 `.vfox/sdks/flutter/bin`。想让那个 SDK 走 vfox 用,用 `vfox link` 把它登记进来,见 [flutter-upgrade.md](flutter-upgrade.md#用其他包管理器装的-sdk)。项目里的选择只在 `.vfox.toml` 所在的目录生效,子目录里不生效;vfox 又是在提示符出现时才改 `PATH`,所以把 `cd project && flutter run` 写在一行里,运行的还是上一个目录的 Flutter,见 [use-cases.md](use-cases.md#项目用不同的-flutter-版本)。 +- **`flutter` 运行的不是 `vfox use` 选的那个 Flutter。** `PATH` 里更靠前的另一个 Flutter 会胜出,比如手动装在 `~/develop/flutter` 的,或者包管理器(Homebrew、mise、asdf、FVM)装的。`command -v flutter` 能看到实际运行的是哪一个,它的路径应当以 `~/.vfox/sdks/flutter/bin` 开头,在项目里则是 `.vfox/sdks/flutter/bin`。想让那个 SDK 走 vfox 用,执行 `vfox link --detect flutter`(自定义位置用 `vfox link flutter@<名字> <路径>`),见 [flutter-upgrade.md](flutter-upgrade.md#用其他包管理器装的-sdk)。项目里的选择只在 `.vfox.toml` 所在的目录生效,子目录里不生效;vfox 又是在提示符出现时才改 `PATH`,所以把 `cd project && flutter run` 写在一行里,运行的还是上一个目录的 Flutter,见 [use-cases.md](use-cases.md#项目用不同的-flutter-版本)。 - **Flutter 说“A new version of Flutter is available!”并建议执行 `flutter upgrade`。** 别理它:`flutter upgrade` 会在 vfox 的背后改动 SDK,见 [flutter-upgrade.md](flutter-upgrade.md)。`vfox install flutter@stable` 才是升级。`flutter --no-version-check` 可以不显示这条提示。 - **`FLUTTER_ROOT` 没有设置。** 插件只设置 `PATH`。`flutter` 脚本会自己找到它所在的目录。 - **没有装 Dart 插件,`dart` 却在。** Flutter SDK 包含 Dart SDK,`dart` 就在它的 `bin` 里。不需要再另外添加 [vfox-dart](https://github.com/version-fox/vfox-dart) 插件。 diff --git a/hooks/detect.lua b/hooks/detect.lua new file mode 100644 index 0000000..46767e6 --- /dev/null +++ b/hooks/detect.lua @@ -0,0 +1,23 @@ +-- Copyright 2026 Han Li and contributors +-- +-- Licensed under the Apache License, Version 2.0 (the "License"); +-- you may not use this file except in compliance with the License. +-- You may obtain a copy of the License at +-- +-- http://www.apache.org/licenses/LICENSE-2.0 +-- +-- Unless required by applicable law or agreed to in writing, software +-- distributed under the License is distributed on an "AS IS" BASIS, +-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +-- See the License for the specific language governing permissions and +-- limitations under the License. + +local detect = require("detect_sdk") + +-- Find Flutter SDKs that are already on this machine for +-- `vfox link --detect flutter`: Homebrew, mise, asdf, FVM and manual +-- installs in their usual places. Anything elsewhere is for +-- `vfox link flutter@ `. +function PLUGIN:Detect(ctx) + return detect.find() +end diff --git a/lib/detect_sdk.lua b/lib/detect_sdk.lua new file mode 100644 index 0000000..96e6595 --- /dev/null +++ b/lib/detect_sdk.lua @@ -0,0 +1,256 @@ +-- Copyright 2026 Han Li and contributors +-- +-- Licensed under the Apache License, Version 2.0 (the "License"); +-- you may not use this file except in compliance with the License. +-- You may obtain a copy of the License at +-- +-- http://www.apache.org/licenses/LICENSE-2.0 +-- +-- Unless required by applicable law or agreed to in writing, software +-- distributed under the License is distributed on an "AS IS" BASIS, +-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +-- See the License for the specific language governing permissions and +-- limitations under the License. + +-- Find Flutter SDKs that are already on this machine for `vfox link --detect`. +-- A candidate is a directory whose `bin` holds `flutter` (or `flutter.bat`) +-- and whose root `version` file names the release. Google ships a full `.git` +-- checkout in every release archive no matter who downloads it, so the same +-- directories work no matter which manager put them there. Only fixed, +-- well-known locations are scanned; anything elsewhere is for +-- `vfox link flutter@ `. +-- +-- NOTE: this file is not called `detect.lua`: vfox searches `hooks/` before +-- `lib/`, so `require("detect")` would load `hooks/detect.lua` instead and +-- loop. +local M = {} + +local function sep() + if RUNTIME.osType == "windows" then + return "\\" + end + return "/" +end + +local function p(...) + return table.concat({ ... }, sep()) +end + +-- Quote a path for the platform shell, the same rule as `lib/git.lua` and +-- `lib/manifest.lua`: double quotes around a path with whitespace on Windows +-- (vfox 1.0.13 and later pass it through verbatim), single quotes elsewhere. +local function quote(value) + if RUNTIME.osType == "windows" then + if value:find("%s") then + return '"' .. value .. '"' + end + return value + end + return "'" .. value:gsub("'", "'\\''") .. "'" +end + +local function trim(s) + if type(s) ~= "string" then + return nil + end + local t = s:match("^(.-)%s*$") + if t == "" then + return nil + end + return t +end + +local function readable(path) + local f = io.open(path, "rb") + if f == nil then + return false + end + f:close() + return true +end + +local function readTrimmed(path) + local f = io.open(path, "rb") + if f == nil then + return nil + end + local content = f:read("*a") + f:close() + return trim(content) +end + +-- Names vfox accepts for a linked version: the same rule as core's +-- ValidVersionName (letters, digits, `.`, `_`, `+` and `-`, never `latest`). +function M.validName(name) + if type(name) ~= "string" or name == "" or name == "latest" then + return false + end + return name:match("^[A-Za-z0-9][A-Za-z0-9._%+%-]*$") ~= nil +end + +local function isSdkDir(dir) + if type(dir) ~= "string" or dir == "" then + return false + end + local bin = p(dir, "bin") + return readable(p(bin, "flutter")) or readable(p(bin, "flutter.bat")) +end + +-- The release name from the SDK's own `version` file, or nil when it is +-- missing or not a name vfox could link under. +local function sdkVersion(dir) + local v = readTrimmed(p(dir, "version")) + if v ~= nil and M.validName(v) then + return v + end + return nil +end + +-- Immediate children of dir, sorted. Listing runs a process (`ls` on POSIX, +-- `dir` on Windows); Detect only runs for `vfox link --detect`, never on +-- `vfox use`, so that is fine here (unlike the Fingerprint hook, which must +-- stay under 50 ms and only reads files). A missing directory lists as +-- nothing, never as an error. +local function listNames(dir) + if type(dir) ~= "string" or dir == "" then + return {} + end + local cmd + if RUNTIME.osType == "windows" then + cmd = "dir /b /ad " .. quote(dir) + else + cmd = "ls -1 " .. quote(dir) + end + local ok, pipe = pcall(io.popen, cmd) + if not ok or pipe == nil then + return {} + end + local okRead, content = pcall(function() + return pipe:read("*a") + end) + pcall(function() + pipe:close() + end) + if not okRead or type(content) ~= "string" then + return {} + end + local names = {} + for line in (content .. "\n"):gmatch("(.-)\n") do + local name = trim(line) + if name ~= nil then + table.insert(names, name) + end + end + table.sort(names) + return names +end + +local function homes() + local out, seen = {}, {} + for _, v in ipairs({ os.getenv("HOME"), os.getenv("USERPROFILE") }) do + if type(v) == "string" and v ~= "" and not seen[v] then + seen[v] = true + table.insert(out, v) + end + end + return out +end + +local function envDir(name) + local v = os.getenv(name) + if type(v) == "string" and v ~= "" then + return v + end + return nil +end + +local function probe(dir, label, out, seen) + if type(dir) ~= "string" or dir == "" or seen[dir] then + return + end + seen[dir] = true + if not isSdkDir(dir) then + return + end + local version = sdkVersion(dir) + if version == nil then + return + end + table.insert(out, { version = version, path = dir, note = label }) +end + +-- Where to look, in order. `multi` roots hold one SDK per sub directory +-- (optionally one level deeper via `sub`, like Homebrew's `/flutter`); +-- `single` entries are probed as SDKs themselves. +local function roots() + local list = {} + local function addMulti(path, sub, label) + table.insert(list, { multi = true, path = path, sub = sub, label = label }) + end + local function addSingle(path, label) + table.insert(list, { multi = false, path = path, label = label }) + end + local hs = homes() + if RUNTIME.osType == "darwin" then + -- Homebrew keeps one directory per release, with the SDK inside it. + addMulti("/opt/homebrew/Caskroom/flutter", "flutter", "Homebrew") + addMulti("/usr/local/Caskroom/flutter", "flutter", "Homebrew") + end + -- mise and asdf keep one directory per installed version. + local mise = envDir("MISE_DATA_DIR") + if mise ~= nil then + addMulti(p(mise, "installs", "flutter"), nil, "mise") + end + local asdf = envDir("ASDF_DATA_DIR") + if asdf ~= nil then + addMulti(p(asdf, "installs", "flutter"), nil, "asdf") + end + for _, h in ipairs(hs) do + addMulti(p(h, ".local", "share", "mise", "installs", "flutter"), nil, "mise") + addMulti(p(h, ".asdf", "installs", "flutter"), nil, "asdf") + addMulti(p(h, "fvm", "versions"), nil, "FVM") + end + if RUNTIME.osType == "windows" then + -- C:\src\flutter is the path Flutter's own install guide uses. + addSingle("C:\\src\\flutter", "manual install") + for _, h in ipairs(hs) do + addSingle(p(h, "flutter"), "manual install") + addSingle(p(h, "scoop", "apps", "flutter", "current"), "Scoop") + end + else + for _, h in ipairs(hs) do + addSingle(p(h, "development", "flutter"), "manual install") + addSingle(p(h, "develop", "flutter"), "manual install") + addSingle(p(h, "flutter"), "manual install") + end + addSingle("/opt/flutter", "manual install") + addSingle("/usr/local/flutter", "manual install") + end + return list +end + +-- Every Flutter SDK on this machine that lives in a well-known place, as +-- `{ version, path, note }` entries for `vfox link --detect`. vfox itself +-- skips what is already installed or linked. Nil when there is nothing. +function M.find() + local out, seen = {}, {} + for _, root in ipairs(roots()) do + if root.multi then + for _, name in ipairs(listNames(root.path)) do + local cand = p(root.path, name) + if root.sub ~= nil then + cand = p(cand, root.sub) + end + probe(cand, root.label, out, seen) + end + else + probe(root.path, root.label, out, seen) + end + end + if #out == 0 then + return nil + end + return out +end + +return M diff --git a/tests/hooks_test.lua b/tests/hooks_test.lua index 807f3bb..8e22bce 100644 --- a/tests/hooks_test.lua +++ b/tests/hooks_test.lua @@ -19,7 +19,14 @@ local fixture, requests, mirror, sleeps -- of the request that returns what http.get returns, and the releases that its 200 carries. local gitcode, gitcodeReleases local originalGetenv = os.getenv +-- A test sets testEnvOverrides to run with a scratch environment instead of +-- the real one: lookups hit the table first, and anything it does not name +-- reads as absent. +local testEnvOverrides = nil os.getenv = function(name) + if testEnvOverrides ~= nil then + return testEnvOverrides[name] + end if name == "FLUTTER_STORAGE_BASE_URL" then return mirror end @@ -692,6 +699,106 @@ tests[#tests + 1] = { equal(out3.version, "3.47.4") end, } +tests[#tests + 1] = { + "Detect only names versions vfox could link", + function() + setup("linux", "amd64") + local detect = require("detect_sdk") + assert(detect.validName("3.47.4") == true) + assert(detect.validName("3.50.0-0.1.pre") == true) + assert(detect.validName("3.41.10-ohos-1.0.0") == true) + assert(detect.validName("latest") == false) + assert(detect.validName("") == false) + assert(detect.validName(nil) == false) + assert(detect.validName("../escape") == false) + assert(detect.validName("a/b") == false) + assert(detect.validName("a b") == false) + assert(detect.validName(".hidden") == false) + assert(detect.validName("-x") == false) + end, +} +tests[#tests + 1] = { + "Detect finds manager and manual installs by their version file", + function() + setup("linux", "amd64") + dofile("hooks/detect.lua") + local base = os.tmpname() + os.remove(base) + local function write(path, text) + local dir = path:match("^(.+)/[^/]+$") + os.execute("mkdir -p '" .. dir .. "'") + local f = assert(io.open(path, "wb")) + f:write(text or "") + f:close() + end + local function sdk(root, version) + write(root .. "/bin/flutter", "#!/bin/sh\n") + os.execute("chmod +x '" .. root .. "/bin/flutter'") + if version ~= nil then + write(root .. "/version", version .. "\n") + end + end + -- a mise-style versioned install, an asdf-style one, an FVM one and + -- a manual one, plus three directories that are not SDKs + sdk(base .. "/mise/installs/flutter/3.47.4", "3.47.4") + sdk(base .. "/mise/installs/flutter/junk-no-bin", nil) + sdk(base .. "/asdf/installs/flutter/3.44.0", "3.44.0") + sdk(base .. "/fvm/versions/3.50.0-0.1.pre", "3.50.0-0.1.pre") + sdk(base .. "/manual/flutter", "2.10.0") + sdk(base .. "/stripped/flutter", nil) + write(base .. "/asdf/installs/flutter/empty/version", "latest\n") + testEnvOverrides = { + HOME = base .. "/home", + MISE_DATA_DIR = base .. "/mise", + ASDF_DATA_DIR = base .. "/asdf", + } + -- $HOME only holds the FVM and manual installs here + os.execute("mkdir -p '" .. base .. "/home/fvm/versions'") + os.execute("cp -r '" .. base .. "/fvm/versions/3.50.0-0.1.pre' '" .. base .. "/home/fvm/versions/'") + os.execute("cp -r '" .. base .. "/manual/flutter' '" .. base .. "/home/flutter'") + local found = PLUGIN:Detect({}) + testEnvOverrides = nil + assert(found ~= nil and #found == 4, "expected 4 SDKs, got " .. tostring(found and #found)) + local byVersion = {} + for _, info in ipairs(found) do + byVersion[info.version] = info + end + equal(byVersion["3.47.4"].note, "mise") + assert(byVersion["3.47.4"].path == base .. "/mise/installs/flutter/3.47.4", byVersion["3.47.4"].path) + equal(byVersion["3.44.0"].note, "asdf") + equal(byVersion["3.50.0-0.1.pre"].note, "FVM") + equal(byVersion["2.10.0"].note, "manual install") + -- nothing to find reads as nothing found + testEnvOverrides = { HOME = base .. "/nosuch" } + assert(PLUGIN:Detect({}) == nil) + testEnvOverrides = nil + os.execute("rm -rf '" .. base .. "'") + end, +} +tests[#tests + 1] = { + "Detect lists directories the Windows way there", + function() + setup("linux", "amd64") + dofile("hooks/detect.lua") + local seen = {} + local popen = io.popen + rawset(io, "popen", function(cmd) + table.insert(seen, cmd) + return nil + end) + RUNTIME = { osType = "windows", archType = "amd64" } + testEnvOverrides = { HOME = "C:\\Users\\tester" } + assert(PLUGIN:Detect({}) == nil) + testEnvOverrides = nil + rawset(io, "popen", popen) + RUNTIME = { osType = "linux", archType = "amd64" } + local listed = false + for _, cmd in ipairs(seen) do + listed = listed or cmd:find("dir /b", 1, true) ~= nil + end + assert(listed, "Detect must list directories with dir on Windows") + end, +} local failures = 0 for _, test in ipairs(tests) do