Release 1.4.0: origin-signed engine (ITMS-91065) + App Store blockers + pub workspace support

[MAUstaoglu]

Ships the last of the App Store submission blockers. The tvOS engine artifact is now origin-signed (published as v1.0.1-flutter3.44.5), so downstream apps clear Apple's commonly-used-SDK signature check at external review.

Engine / signing (ITMS-91065)

• The tvOS engine artifact now ships origin-signed (Developer ID Application, hardened runtime + secure timestamp), the same way flutter.dev signs its iOS artifacts. Apps embedding an unsigned engine were rejected with ITMS-91065 ("Missing signature") only at external Beta App Review / App Store review — an app-identity re-sign at export does not satisfy the check; the artifact itself must carry the origin signature.
• bin/internal/engine.version → v1.0.1-flutter3.44.5 (same Flutter 3.44.5 build, re-published signed).
• Engine tooling (separate PR in fluttertv/engine): build.sh --signing-identity + a verify_artifacts.sh origin-sign gate.

Fixed

• Custom fragment shaders render on tvOS/Metal — TvosCopyFlutterBundle copied assets as TargetPlatform.android, so every .frag shipped without the Metal runtime stage and failed at runtime. (fix: bundle fragment shaders with the Metal runtime stage #34)
• Pub-workspace plugin discovery — a tvOS app that is a workspace member found no plugins (package_config.json is hoisted to the workspace root); discovery now walks up to it. (Plugin discovery does not support Dart pub workspaces #29, fix: plugin discovery finds package_config.json in pub workspaces #32)
• Pod script phases get FLUTTER_ROOT + flutter_export_environment.sh so cargokit/Rust-FFI tooling can locate the Dart SDK. (fix: write FLUTTER_ROOT and flutter_export_environment.sh for pod script phases #33)
• AOT intermediates no longer leak into flutter_assets (App Store rejection).
• App.framework min-version matches MinimumOSVersion (13.0) — ITMS-90208.
• Complete tvOS app-icon template catalog (@2x layers + Top Shelf Wide) required by asset validation.

Added

• Build-time migration warning for existing projects whose app-icon catalog predates the completed template.
• A "Sign Flutter.framework" build phase (re-signs the SPM-embedded engine to the app's own team for device installs).

Tests

286 passing. New regression coverage for pub-workspace discovery (verified failing on pre-fix main), the AOT-intermediate leak, both AOT clang min-version calls, the template catalog, the migration warning, and the FLUTTER_ROOT / flutter_export_environment.sh generation.

Verified end-to-end: a clean flutter-tvos build tvos --release produces App.framework with minos 13.0, no AOT leakage, and consumes the origin-signed engine (verify_artifacts.sh green, authority = Developer ID Application → Apple Root CA).

Closes #29

[DenisovAV]

Reviewed this against the real artifacts and the real code — including downloading tvos_release_arm64.zip and running codesign on it, and compiling with the min-version flags to check the resulting Mach-O. The headline claims all hold up. A few things to fix, and one pre-existing bug that I think should block the tag.

Verified — these are genuinely done

• The engine artifact really is origin-signed. v1.0.1-flutter3.44.5 exists, and codesign -dvvv on the downloaded release shows Authority=Developer ID Application: MEHMET ALI USTAOGLU (866PPL96Z4), flags=0x10000(runtime) (hardened runtime), and a secure timestamp — on both the bare Flutter.framework and the tvos-arm64 xcframework slice. All 6 asset names match _artifactZipNames exactly, so precache won't break on merge. ITMS-91065 is actually addressed, not just plausibly.
• The AOT-intermediate fix does not over-exclude. I diffed the hand-mirrored TvosCopyFlutterBundle.build line-by-line against upstream CopyFlutterBundle.build — byte-identical apart from TargetPlatform.android → .ios. The if (buildMode == BuildMode.debug) gate that copies kernel_blob.bin/vm_snapshot_data/isolate_snapshot_data is preserved verbatim, and the new skip list is guarded by entity is Directory, so those files can't be dropped. Debug/JIT is safe.
• The shader fix is load-bearing and correct. _shaderTargetsFromTargetPlatform gives android → [--sksl, --runtime-stage-gles, --runtime-stage-gles3, --runtime-stage-vulkan] (no Metal) and ios → [--runtime-stage-metal]. copyAssets threads it straight to impellerc. Right value, and it matches what the rest of the repo already uses for tvOS (tvos_device.dart:372, tvos_builder.dart:44).
• ITMS-90208 can't silently regress. sdkName is effectively an enum (tvos_build_info.dart:18 → 'appletvos' | 'appletvsimulator'), so the simulator-flag-on-device direction is unreachable, and an unknown value falls back to the device flag (fails loudly at link rather than shipping a bad minos). _kTvosMinimumOSVersion feeds both the clang flag and App.framework's MinimumOSVersion, so the two values ITMS-90208 compares match by construction. Confirmed empirically: no flag → minos 26.5 (the bug); with the flag → minos 13.0.
• The codesign phase does not swallow failures (codesign is the last command in the else, so its exit code is the phase's), the simulator path skips correctly, and --timestamp=none is upstream's own convention for embedded-framework re-signing.

Also: the code comments are honest that the re-sign phase does not by itself satisfy ITMS-91065. That distinction trips people up constantly, and getting it right in the comments is worth calling out.

---

🔴 The one I'd fix before tagging — clean release builds ship with no flutter_assets

lib/build_targets/application.dart:855. Pre-existing (since 1.0.0), not introduced here — but it's three lines from code this PR edits, and it's precisely the "green build, rejected/broken later" class this release exists to eliminate.

if (tvosOutputDir.childFile('kernel_blob.bin').existsSync()) {
  flutterAssetsSource = tvosOutputDir;      // build/tvos/
} else if (defaultDir.existsSync()) {
  flutterAssetsSource = defaultDir;         // build/flutter_assets/ — never written for tvOS
}
...
} else {
  globals.logger.printTrace('flutter_assets not found in build output, skipping.');
}

kernel_blob.bin is written only in debug (upstream, and this PR's mirror preserves that). In release, copyAssets still fills build/tvos/ with AssetManifest.bin, fonts/, assets/, shaders/ — but there's no kernel_blob.bin, so the probe is false. The fallback checks build/flutter_assets/, which the tvOS build never writes (outputDir is build/tvos — tvos_builder.dart:39). So flutterAssetsSource == null, the copy is skipped, and the only trace of it is a printTrace.

Failure scenario: rm -rf build && flutter-tvos build tvos --release (i.e. any fresh clone or CI runner). tvos/Flutter/flutter_assets is never created, the Xcode phase prints warning: flutter_assets not found, the build goes green, and the archive ships with zero assets — MaterialIcons boxes, Unable to load asset, blank screens at runtime.

Why it hasn't bitten: anyone who ran a debug build first leaves a stale build/tvos/kernel_blob.bin behind, the probe passes, and the freshly-written release assets get copied. Invisible on a dev machine, fatal on clean CI.

Probe for something that exists in every mode, and make the miss fatal — there is no legitimate build in which a Flutter app has no assets:

if (tvosOutputDir.childFile('AssetManifest.bin').existsSync()) {
  flutterAssetsSource = tvosOutputDir;
} else if (defaultDir.existsSync()) {
  flutterAssetsSource = defaultDir;
} else {
  throwToolExit(
    'No Flutter assets found in ${tvosOutputDir.path}. The asset bundling step did '
    'not run. Try "flutter-tvos clean" and rebuild; if it persists, file an issue.',
  );
}

---

Also worth fixing (details inline)

1. COCOAPODS_PARALLEL_CODE_SIGN is written only to the .sh, where it does nothing — and the new test pins that. Inline.
2. flutter-tvos clean doesn't remove flutter_export_environment.sh. lib/commands/clean.dart:28 cleans Generated.xcconfig but not its new sibling — and this is the PR that starts writing that file. A stale script with an absolute FLUTTER_ROOT survives a clean; a user who then moves the project and builds from Xcode gets cargokit sourcing a dead SDK path. tvos_clean_test.dart already exists and already asserts on Generated.xcconfig, so it's two lines total:

   _cleanFile(tvosDir, 'Flutter/flutter_export_environment.sh');

3. The sign phase's not-found branch is a warning on the one build where it's fatal, and ${PRODUCT_NAME}.app is the wrong path. Inline.
4. appIconCatalogNeedsMigration has a false negative on the exact remediation path its own warning recommends. Inline.
5. The shader fix — the headline #34 item — has no test. TvosCopyFlutterBundle.build is the most fragile code in the PR (a hand-mirror of upstream that must be re-synced on every Flutter upgrade, as its own comment says), and nothing asserts copyAssets is called with targetPlatform: TargetPlatform.ios. A FakeProcessManager/spy assertion on that one argument would guard the whole thing. Same shape for tvosVersionMinFlag: the argv-builder statics are well tested, but nothing asserts the production call sites pass the flag — you could pass '' at application.dart and every new test stays green.

Minor

• lib/tvos_plugins.dart keeps a hand-rolled upward walk where flutter_tools already ships one — and this repo already uses it: tvos_builder.dart:79 → findPackageConfigFileOrDefault(project.directory). Inline.
• CHANGELOG references engine/build.sh --signing-identity and engine/verify_artifacts.sh, but there's no engine/ directory in this repo — those live in fluttertv/engine. Worth annotating so readers don't hunt for them here.

---

Nothing here undermines the release: the signing, the shader fix, the min-version fix and the AOT fix are all real and verified. But every new guard in this PR is advisory (printWarning / printTrace), on a release whose whole purpose is eliminating failures that only surface days later at review — and three of them can report "looks fine" on a project that will be rejected. The application.dart:855 probe is the one I'd genuinely hold the tag for.

[DenisovAV]

COCOAPODS_PARALLEL_CODE_SIGN=true is written only into flutter_export_environment.sh, so as shipped it does nothing.

It's consumed by CocoaPods' [CP] Embed Pods Frameworks phase as an Xcode build setting — that phase never sources this script. cargokit ignores it too. Upstream builds a single xcodeBuildSettings list and feeds it to both writers (xcode_build_settings.dart:50 → Generated.xcconfig, :56 → the .sh, emitting export "$line" per entry), adding this var at :185. So upstream's .sh is a strict subset of the xcconfig. Here it's a strict superset — the var exists only where it has no effect.

The tvOS Podfile uses use_frameworks!, so the embed phase does exist and would benefit. One line in buildGeneratedXcconfig:

..writeln('COCOAPODS_PARALLEL_CODE_SIGN=true')

And the new test currently pins the bug: tvos_app_bundle_test.dart asserts expect(sh, contains('export "COCOAPODS_PARALLEL_CODE_SIGN=true"')), while the companion xcconfig test asserts only the six FLUTTER_* vars and says nothing about this one. Net: a test fails if you remove it from the .sh, and no test ever fails for its absence from the xcconfig — so a future fixer has to argue with the suite.

The parity assertion that would actually catch this is the upstream invariant, in this direction: every non-conditional export "K=V" in the .sh must appear as K=V in the xcconfig. (I'd originally suggested the reverse — that one passes today and would have missed it.) Better still, derive both strings from one settings list, the way upstream does, so they can't drift at all.

[DenisovAV]

Two problems in this branch, both of which end in "green build, unsigned framework".

1. ${PRODUCT_NAME}.app is the wrong path. The bundle directory is ${WRAPPER_NAME}; the thing to sign is ${CODESIGNING_FOLDER_PATH}. PRODUCT_NAME happens to equal the wrapper base name in the default template, but any target that overrides it (custom product name, flavors, $(inherited) games) resolves FRAMEWORK to a path that doesn't exist.

2. That miss is a warning: with exit 0. On a build where CODE_SIGNING_REQUIRED != NO and EXPANDED_CODE_SIGN_IDENTITY is non-empty, a missing Flutter.framework isn't "nothing to do" — it means the SPM embed didn't happen (or landed elsewhere), and the app ships a nested framework signed by a foreign team. The user finds out at device install (0xe8008014) or at review.

It's also worth noting the Dart-side guard doesn't catch it either: _warnIfFlutterFrameworkUnsigned greps the pbxproj for the literal string 'Sign Flutter.framework', so it reports "fine" whenever the phase exists — including when the phase silently no-op'd. Both guards say OK while nothing was signed. (Consider renaming it _warnIfProjectLacksFlutterSigningPhase — it checks project config, not a signature.)

Reordering the branches so the "do we need to sign at all" check comes first keeps the simulator skipping silently and makes only signing builds hard-fail:

FRAMEWORK="${CODESIGNING_FOLDER_PATH}/Frameworks/Flutter.framework"
if [ "${CODE_SIGNING_REQUIRED}" = "NO" ] || [ -z "${EXPANDED_CODE_SIGN_IDENTITY}" ]; then
  echo "Skipping Flutter.framework signing (code signing not required for this build)."
elif [ ! -d "${FRAMEWORK}" ]; then
  echo "error: Flutter.framework was not embedded at ${FRAMEWORK}. Regenerate the tvOS project."
  exit 1
else
  codesign --force --sign "${EXPANDED_CODE_SIGN_IDENTITY}" --timestamp=none --generate-entitlement-der "${FRAMEWORK}"
fi

(The pre-existing "Embed App.framework" phase makes the same ${PRODUCT_NAME}.app assumption — worth fixing in the same pass, though it's not new here.)

[DenisovAV]

This check has a false negative on exactly the path its own warning tells users to take.

It reads only the top-level Contents.json and only looks for the top-shelf-image-wide role string. It never verifies that the six @2x layer images exist — even though the warning text says the catalog is missing "the @2x icon layers and the Top Shelf Image Wide asset", and the @2x layers are half the rejection cause.

Scenario: a user with custom icons follows the advice to fix the catalog by hand. They do the easy, visible half — paste the top-shelf-image-wide entry into Contents.json — and don't get around to producing six @2x PNGs. Next build: no warning, because the marker string is now present. They archive, upload, and get rejected by asset validation again — with the tool now actively telling them the catalog is fine. A migration warning that goes quiet when you do half the migration is worse than no warning.

Making it structural also gives you a much better message (list exactly what's missing, so it stays actionable and stays on until the migration is actually complete):

@visibleForTesting
static List<String> missingAppIconAssets(Directory tvosProjectDir) {
  final Directory brand = tvosProjectDir
      .childDirectory('Runner').childDirectory('Assets.xcassets')
      .childDirectory('AppIcon.brandassets');
  if (!brand.childFile('Contents.json').existsSync()) return const <String>[];
  final missing = <String>[];
  if (!brand.childFile('Contents.json').readAsStringSync().contains('top-shelf-image-wide')) {
    missing.add('the "top-shelf-image-wide" role in AppIcon.brandassets/Contents.json');
  }
  for (final stack in const <String>['Small', 'Large']) {
    for (final layer in const <String>['Back', 'Middle', 'Front']) {
      final File f = brand
          .childDirectory('App Icon - $stack.imagestack')
          .childDirectory('$layer.imagestacklayer')
          .childDirectory('Content.imageset')
          .childFile('${stack.toLowerCase()}_${layer.toLowerCase()}@2x.png');
      if (!f.existsSync()) missing.add(f.path);
    }
  }
  return missing;
}

Two smaller things in the same method: readAsStringSync() is uncaught (an unreadable catalog crashes the tool with a stack trace rather than a message), and the hard-coded Runner/ directory means a renamed target silently returns false.

Separately — severity. This fires at step 6b, then pod install and a multi-minute Xcode spinner scroll it away. There's no build ipa/archive command in the CLI, so the submission path is the user archiving from Xcode; this line is the only chance to reach them. For an incomplete catalog on a --release device build the outcome is deterministic and known (asset validation rejects the archive). At minimum re-emit both warnings after Xcode build done. as the last thing on screen; ideally throwToolExit for release+device. The message text itself is genuinely good — it's the severity and the placement that undercut it.

[DenisovAV]

This hand-rolls an upward walk that flutter_tools already ships as findPackageConfigFile / findPackageConfigFileOrDefault (dart/package_map.dart:25,48), exposed as FlutterProject.packageConfig (project.dart:227). Upstream's own findPlugins() — the direct analogue of this function — uses it (flutter_plugins.dart:109).

And this repo already calls it: lib/tvos_builder.dart:79 → findPackageConfigFileOrDefault(project.directory).path. So after this PR the build resolves package_config.json with upstream semantics in one place and hand-rolled semantics in another, in the same build. They can disagree — see below.

_walkPluginDependencies already takes a FlutterProject and project.dart is already imported, so this is a one-line swap with no new imports:

final File packageConfigFile = project.packageConfig;

Two real differences you get for free:

1. Upstream normalizes/absolutizes first (fileSystem.path.normalize(dir.absolute.path)). This version walks project.directory as-is — and for a relative directory, path.dirname('.') == '.', so the termination condition trips on the first check and the walk silently never happens, reintroducing the very workspace bug this hunk exists to fix. It doesn't bite today because project.directory is always absolute, but that's a property of the callers, not of this code.
2. Upstream terminates on fileSystem.path.equals(...), not a raw string != (case/separator-insensitive on macOS/Windows).

Good news: the new tvos_workspace_plugin_discovery_test.dart drives the public discoverTvosSpmPlugins and asserts only on names and resolved paths — it doesn't pin the walk. So the swap stays green and the test keeps guarding the behavior.