feat(package_info_plus): add opt-in compile-time package info accessor

[Ortes]

Description

On the web, PackageInfo.fromPlatform() resolves the version by fetching version.json from the server at runtime (with a cache buster). That file reflects whatever is currently deployed — not the bundle actually executing in the browser. The two states routinely diverge:

• A user running a stale, cached bundle gets the newly deployed version reported ([Bug]: [package_info_plus] Web: Version info returns next version in server #2675).
• The fetch can also fail outright (offline [package_info_plus] Web: fail to get PackageInfo (version) offline #456, CORS, hosting rewrites, extension contexts [Bug]: ClientException: Invalid content-length header [-1] when reading version.json on a Firefox extension #3028), leaving every field empty.

This makes the reported version actively misleading rather than merely missing — and the version is the whole point of the plugin. Its two canonical uses, showing the running version and checking whether an update is needed, are both defeated when the value is the server's. An update gate built on it can never fire for the very users it targets, since stale clients self-report as up to date.

This PR

Adds a small opt-in library, package_info_plus_environment.dart, exposing PackageInfoEnvironment.packageInfo:

import 'package:package_info_plus/package_info_plus_environment.dart';

final info = await PackageInfoEnvironment.packageInfo;

• Web — returns a PackageInfo built from compile-time PACKAGE_INFO_PLUS_* defines (flutter build web --dart-define=PACKAGE_INFO_PLUS_VERSION=1.2.3 ...). These are embedded in the running bundle and cannot diverge from it. A web build that omits PACKAGE_INFO_PLUS_VERSION fails to compile (a kIsWeb-conditional const assert), so a misleading version can never ship silently.
• All other platforms — delegates to PackageInfo.fromPlatform(), which reads the installed binary and is already reliable. The defines are not required there.

Design choices that keep this safe and non-breaking:

• PackageInfo.fromPlatform() is untouched. No behavior change for existing users.
• Opt-in via a separate library that the package barrel does not export. The compile-time guard is evaluated per compiled library, so it only affects code that explicitly imports package_info_plus_environment.dart. Apps that don't opt in are completely unaffected — no new build requirement is imposed package-wide.
• Cross-platform by construction (single accessor, platform-appropriate source), per the contributing guide's rule against single-platform features.
• The framework-side requests to expose the build version were declined ("Static" versioning in flutter web flutter/flutter#149725, [WEB] Web Cache invalidation based on pubspec.yaml version flutter/flutter#149031), so a plugin-level opt-in seems to be the only avenue available to users today. If Flutter later injects build name/number defines, this accessor can read them with no API change.

flutter analyze is clean and the existing + new tests pass. The web compile-time enforcement is verified by a compilation test (a web build without the define does not compile) rather than a runtime test.

Related Issues

• Fix [Bug]: [package_info_plus] Web: Version info returns next version in server #2675
• Related [package_info_plus] Web: Version info may be stale due to caching. #225
• Related [package_info_plus] Web: fail to get PackageInfo (version) offline #456
• Related [Bug]: ClientException: Invalid content-length header [-1] when reading version.json on a Firefox extension #3028
• Related [WEB] Web Cache invalidation based on pubspec.yaml version flutter/flutter#149031

Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I titled the PR using Conventional Commits.
• I did not modify the CHANGELOG.md nor the plugin version in pubspec.yaml files.
• All existing and new tests are passing.
• The analyzer (flutter analyze) does not report any problems on my PR.

Breaking Change

• Yes, this is a breaking change.
• No, this is not a breaking change.

[Ortes]

Re: CI status — the red checks here are pre-existing infrastructure failures, not regressions from this PR. Evidence:

The jobs that actually exercise this change all pass:

• Dart Analyzer ✓ · web_example_build ✓ · android_integration_test (24) ✓ · linux/windows build + integration ✓

The failing jobs fail identically on main and on every recent unrelated PR:

• all_plugins analyze/pub-check fails on a sensors_plus invalid_annotation_target warning (unrelated package) — red on every PR including ones targeting main.
• macos_example_build / ios_example_build: Plugin package_info_plus has a Package.swift for macos but is missing a dependency on FlutterFramework + CocoaPods xcfilelist errors — Xcode/SPM toolchain drift on the runners.
• android_integration_test (shards 29/32/36): Timeout waiting for emulator to boot — emulator flake; shard 24 booted and passed.
• web_integration_test: AppConnectionException from chromedriver, then a 30-min hang until cancel — driver flake, not a compile error (the web example compiles and launches in the log).

The last ~6 package_info_plus PRs (kotlin-dsl migration, ubuntu-24.04 migration, win32 relax, built-in-kotlin) are all red for the same reasons.

This change is purely additive: a new, non-exported package_info_plus_environment.dart library. It doesn't touch any existing code path, and the barrel (package_info_plus.dart) is unchanged — so existing consumers and the example's web build are unaffected. Happy to rebase once the CI infra is sorted.

[Ortes]

Forward-compatibility note. This PR now also recognizes tool-provided version defines as fallbacks, so apps will need no configuration at all once their build front-end injects the version itself:

• FLUTTER_BUILD_NAME / FLUTTER_BUILD_NUMBER — proposed in Expose the app's build name and number as compile-time constants flutter/flutter#187935 (injected by flutter_tools from the pubspec version, like FLUTTER_APP_FLAVOR).
• dart.package.version — companion proposal for the dart CLI, Have a way to retrieve the version from pubspec dart-lang/sdk#38855 (CL https://dart-review.googlesource.com/c/sdk/+/512380).

Resolution order is: explicit PACKAGE_INFO_PLUS_VERSION → FLUTTER_BUILD_NAME → dart.package.version. The two upstream proposals and this PR are deliberately complementary: at least one of them needs to exist for PackageInfo to stop silently reporting the wrong version on web, and whichever lands first makes this plugin correct-by-default there.

[Ortes]

Resolved by flutter/flutter#187934