[infra] Split up package:native_assets_cli (#2259)

Closes: #999

Splits up `package:native_assets_cli` in `package:hooks`, `package:code_assets` and `package:data_assets`.
Renames `package:native_assets_builder` to `package:hooks_runner`.

The dependencies are as follows:

* `hooks` has dev dependencies on `code_assets` and `data_assets` because all the integration tests use these asset types.
* `hooks_runner` has a dependency on `code_assets` due to the kernel-encoding `KernelAssets` which is used to bundle the code-assets asset-mapping in various SDKs.
* `hooks_runner` has a dev dependency on `data_assets` because the integration tests use it.

Versions:

* The split up packages continue numbering from the original version. (It doesn't really matter, we'll need to go to 1.0.0 in the future anyway.)

Internal package structure:

* This PR does not reorganize packages. It moves the files exactly to the same path. This could use cleanup, but let's try to get this PR as small as possible.

CI:

* Two workflows are combined. (This could likely use some cleanup, especially trying to collect coverage across all packages in the workspace instead of a single package at the time.)

Publishing:

* These packages will now need their autopublishing set up. I'll do this after we bump the version to non-wip.

Rolling:

* This will need to be rolled into the Dart and Flutter SDKs. Changing the dependencies there and fixing whatever test setup explicitly mentioning the package names.

Author: dcharkes

.github/ISSUE_TEMPLATE/code_assets.md

@@ -0,0 +1,5 @@
+---
+name: "package:code_assets"
+about: "Create a bug or file a feature request against package:code_assets."
+labels: "package:code_assets"
+---

.github/ISSUE_TEMPLATE/data_assets.md

@@ -0,0 +1,5 @@
+---
+name: "package:data_assets"
+about: "Create a bug or file a feature request against package:data_assets."
+labels: "package:data_assets"
+---

.github/ISSUE_TEMPLATE/hooks.md

@@ -0,0 +1,5 @@
+---
+name: "package:hooks"
+about: "Create a bug or file a feature request against package:hooks."
+labels: "package:hooks"
+---

.github/ISSUE_TEMPLATE/hooks_runner.md

@@ -0,0 +1,5 @@
+---
+name: "package:hooks_runner"
+about: "Create a bug or file a feature request against package:hooks_runner."
+labels: "package:hooks_runner"
+---

.github/ISSUE_TEMPLATE/native_assets_builder.md

@@ -20,13 +20,21 @@
   - changed-files:
     - any-glob-to-any-file: 'pkgs/jnigen/**'
 
-'package:native_assets_builder':
+'package:code_assets':
   - changed-files:
-    - any-glob-to-any-file: 'pkgs/native_assets_builder/**'
+    - any-glob-to-any-file: 'pkgs/code_assets/**'
 
-'package:native_assets_cli':
+'package:data_assets':
   - changed-files:
-    - any-glob-to-any-file: 'pkgs/native_assets_cli/**'
+    - any-glob-to-any-file: 'pkgs/data_assets/**'
+
+'package:hooks':
+  - changed-files:
+    - any-glob-to-any-file: 'pkgs/hooks/**'
+
+'package:hooks_runner':
+  - changed-files:
+    - any-glob-to-any-file: 'pkgs/hooks_runner/**'
 
 'package:native_toolchain_c':
   - changed-files:

.github/ISSUE_TEMPLATE/native_assets_cli.md

@@ -1,13 +1,15 @@
 {
     "CHECKS": {
         "prefixes": [
+            "[code_assets] ",
+            "[data_assets] ",
             "[ffi] ",
             "[ffigen] ",
+            "[hooks_runner] ",
+            "[hooks] ",
             "[infra] ",
             "[jni] ",
             "[jnigen] ",
-            "[native_assets_builder] ",
-            "[native_assets_cli] ",
             "[native_toolchain_c] ",
             "[objective_c] ",
             "[swift2objc] ",

.github/labeler.yml

@@ -10,16 +10,20 @@ on:
     # No `branches:` to enable stacked PRs on GitHub.
     paths:
       - ".github/workflows/native.yaml"
-      - "pkgs/native_assets_builder/**"
-      - "pkgs/native_assets_cli/**"
+      - "pkgs/code_assets/**"
+      - "pkgs/data_assets/**"
+      - "pkgs/hooks_runner/**"
+      - "pkgs/hooks/**"
       - "pkgs/native_toolchain_c/**"
       - "tools/**"
   push:
     branches: [main]
     paths:
       - ".github/workflows/native.yaml"
-      - "pkgs/native_assets_builder/**"
-      - "pkgs/native_assets_cli/**"
+      - "pkgs/code_assets/**"
+      - "pkgs/data_assets/**"
+      - "pkgs/hooks_runner/**"
+      - "pkgs/hooks/**"
       - "pkgs/native_toolchain_c/**"
       - "tools/**"
   schedule:
@@ -32,8 +36,13 @@ jobs:
       matrix:
         os: [ubuntu, macos, windows]
         sdk: [dev]
-        package: [native_assets_builder, native_assets_cli, native_toolchain_c]
-        # Breaking changes temporarily break the example run on the Dart SDK until native_assets_builder is rolled into the Dart SDK dev build.
+        package:
+          - code_assets
+          - data_assets
+          - hooks
+          - hooks_runner
+          - native_toolchain_c
+        # Breaking changes temporarily break the example run on the Dart SDK until hooks_runner is rolled into the Dart SDK dev build.
         breaking-change: [false]
 
     runs-on: ${{ matrix.os }}-latest
@@ -57,10 +66,10 @@ jobs:
       - run: dart pub get
 
       - run: dart pub get -C test_data/native_add_version_skew/
-        if: ${{ matrix.package == 'native_assets_builder' }}
+        if: ${{ matrix.package == 'hooks_runner' }}
 
       - run: dart pub get -C test_data/native_add_version_skew_2/
-        if: ${{ matrix.package == 'native_assets_builder' }}
+        if: ${{ matrix.package == 'hooks_runner' }}
 
       - run: dart analyze --fatal-infos
         # Run on dev to ensure we're not depending on deprecated SDK things.
@@ -75,35 +84,43 @@ jobs:
 
       - run: dart --enable-experiment=native-assets test
         working-directory: pkgs/${{ matrix.package }}/example/build/native_dynamic_linking/
-        if: ${{ matrix.package == 'native_assets_cli' && matrix.sdk == 'dev' && !matrix.breaking-change }}
+        if: ${{ matrix.package == 'hooks' && matrix.sdk == 'dev' && !matrix.breaking-change }}
 
       - run: dart --enable-experiment=native-assets test
         working-directory: pkgs/${{ matrix.package }}/example/build/native_add_app/
-        if: ${{ matrix.package == 'native_assets_cli' && matrix.sdk == 'dev' && !matrix.breaking-change }}
+        if: ${{ matrix.package == 'hooks' && matrix.sdk == 'dev' && !matrix.breaking-change }}
 
       - run: dart --enable-experiment=native-assets run
         working-directory: pkgs/${{ matrix.package }}/example/build/native_add_app/
-        if: ${{ matrix.package == 'native_assets_cli' && matrix.sdk == 'dev' && !matrix.breaking-change }}
+        if: ${{ matrix.package == 'hooks' && matrix.sdk == 'dev' && !matrix.breaking-change }}
 
       - run: dart --enable-experiment=native-assets build bin/native_add_app.dart
         working-directory: pkgs/${{ matrix.package }}/example/build/native_add_app/
-        if: ${{ matrix.package == 'native_assets_cli' && matrix.sdk == 'dev' && !matrix.breaking-change }}
+        if: ${{ matrix.package == 'hooks' && matrix.sdk == 'dev' && !matrix.breaking-change }}
 
       - run: ./native_add_app.exe
         working-directory: pkgs/${{ matrix.package }}/example/build/native_add_app/bin/native_add_app/
-        if: ${{ matrix.package == 'native_assets_cli' && matrix.sdk == 'dev' && !matrix.breaking-change }}
+        if: ${{ matrix.package == 'hooks' && matrix.sdk == 'dev' && !matrix.breaking-change }}
 
       - run: dart --enable-experiment=native-assets test
         working-directory: pkgs/${{ matrix.package }}/example/build/use_dart_api/
-        if: ${{ matrix.package == 'native_assets_cli' && matrix.sdk == 'dev' && !matrix.breaking-change }}
+        if: ${{ matrix.package == 'hooks' && matrix.sdk == 'dev' && !matrix.breaking-change }}
 
       - run: dart --enable-experiment=native-assets test
         working-directory: pkgs/${{ matrix.package }}/example/build/download_asset/
-        if: ${{ matrix.package == 'native_assets_cli' && matrix.sdk == 'dev' && !matrix.breaking-change }}
+        if: ${{ matrix.package == 'hooks' && matrix.sdk == 'dev' && !matrix.breaking-change }}
 
       - run: dart --enable-experiment=native-assets test
         working-directory: pkgs/${{ matrix.package }}/example/build/system_library/
-        if: ${{ matrix.package == 'native_assets_cli' && matrix.sdk == 'dev' && !matrix.breaking-change }}
+        if: ${{ matrix.package == 'hooks' && matrix.sdk == 'dev' && !matrix.breaking-change }}
+
+      - run: |
+          dart tool/generate_schemas.dart
+          dart tool/generate_syntax.dart
+          dart tool/normalize.dart
+          git diff --exit-code
+        working-directory: pkgs/${{ matrix.package }}
+        if: ${{ matrix.package == 'hook' && matrix.sdk == 'dev' }}
 
       - name: Install coverage
         run: dart pub global activate coverage

.github/pr-title-checker-config.json

@@ -38,7 +38,7 @@ new file please also add this. The year should be a single number stating the
 year the file was created (don't use a range like "2011-2012"). Additionally, if
 you edit an existing file, you shouldn't update the year.
 
-    // Copyright (c) 2023, the Dart project authors.  Please see the AUTHORS file
+    // Copyright (c) 2025, the Dart project authors.  Please see the AUTHORS file
     // for details. All rights reserved. Use of this source code is governed by a
     // BSD-style license that can be found in the LICENSE file.
 
@@ -52,10 +52,11 @@ We pledge to maintain an open and welcoming environment. For details, see our
 
 ## Tests
 
-Packages `native_assets_cli`, `native_assets_builder`, and `native_toolchain_c`
-roll into the Dart SDK. The tests of these packages are run on the Dart SDK in
-[a different way](https://github.com/dart-lang/sdk/issues/56574) than on the
-GitHub actions on this repo.
+Packages `hooks`, `code_assets`, `data_assets`, `hooks_runner`, and
+`native_toolchain_c` roll into the Dart SDK. The tests of these packages are run
+on the Dart SDK in [a different
+way](https://github.com/dart-lang/sdk/issues/56574) than on the GitHub actions
+on this repo.
 
 1. The `tools/test.py` runs `(.*)test.dart`, so no `package:test` annotations
    are respected. So, things such as skips should be done with early returns.
@@ -73,4 +74,4 @@ Maven (`mvn` command) to build some sources and run integration tests.
 On Linux and MacOS, it can be installed with the [`sdkman`](https://sdkman.io/)
  package manager or a manual method. On Windows, it can be installed with 
 [chocolatey](https://community.chocolatey.org/packages/maven) or 
-[scoop](https://scoop.sh/#/apps?q=maven).
+[scoop](https://scoop.sh/#/apps?q=maven).

.github/workflows/hooks.yaml

@@ -9,23 +9,27 @@ building and bundling.
 
 | Package | Description | Issues | Version |
 | --- | --- | --- | --- |
+| [code_assets](pkgs/code_assets/) | This package contains the Dart API for code assets in `hook/build.dart` and `hook/link.dart`.  | [![issues](https://img.shields.io/badge/package:code_assets-4774bc)][code_assets_issues] |  |
+| [data_assets](pkgs/data_assets/) | This package contains the Dart API for data assets in `hook/build.dart` and `hook/link.dart`.  | [![issues](https://img.shields.io/badge/package:data_assets-4774bc)][data_assets_issues] |  |
 | [ffi](pkgs/ffi/) | Utilities for working with Foreign Function Interface (FFI) code. | [![issues](https://img.shields.io/badge/package:ffi-4774bc)][ffi_issues] | [![pub package](https://img.shields.io/pub/v/ffi.svg)](https://pub.dev/packages/ffi) |
 | [ffigen](pkgs/ffigen/) | Generator for FFI bindings, using LibClang to parse C, Objective-C, and Swift files. | [![issues](https://img.shields.io/badge/package:ffigen-4774bc)][ffigen_issues] | [![pub package](https://img.shields.io/pub/v/ffigen.svg)](https://pub.dev/packages/ffigen) |
+| [hooks](pkgs/hooks/) | This package contains the API for `hook/build.dart` and `hook/link.dart`. | [![issues](https://img.shields.io/badge/package:hooks-4774bc)][hooks_issues] |  |
+| [hooks_runner](pkgs/hooks_runner/) | This package is the backend that invokes `hook/build.dart` and `hook/link.dart` from Dart and Flutter. | [![issues](https://img.shields.io/badge/package:hooks_runner-4774bc)][hooks_runner_issues] |  |
 | [jni](pkgs/jni/) | A library to access JNI from Dart and Flutter that acts as a support library for package:jnigen. | [![issues](https://img.shields.io/badge/package:jni-4774bc)][jni_issues] | [![pub package](https://img.shields.io/pub/v/jni.svg)](https://pub.dev/packages/jni) |
 | [jnigen](pkgs/jnigen/) | A Dart bindings generator for Java and Kotlin that uses JNI under the hood to interop with Java virtual machine. | [![issues](https://img.shields.io/badge/package:jnigen-4774bc)][jnigen_issues] | [![pub package](https://img.shields.io/pub/v/jnigen.svg)](https://pub.dev/packages/jnigen) |
-| [native_assets_builder](pkgs/native_assets_builder/) | This package is the backend that invokes build hooks. | [![issues](https://img.shields.io/badge/package:native__assets__builder-4774bc)][native_assets_builder_issues] |  |
-| [native_assets_cli](pkgs/native_assets_cli/) | A library that contains the argument and file formats for implementing a native assets CLI. | [![issues](https://img.shields.io/badge/package:native__assets__cli-4774bc)][native_assets_cli_issues] |  |
 | [native_toolchain_c](pkgs/native_toolchain_c/) | A library to invoke the native C compiler installed on the host machine. | [![issues](https://img.shields.io/badge/package:native__toolchain__c-4774bc)][native_toolchain_c_issues] |  |
 | [objective_c](pkgs/objective_c/) | A library to access Objective C from Flutter that acts as a support library for package:ffigen. | [![issues](https://img.shields.io/badge/package:objective__c-4774bc)][objective_c_issues] | [![pub package](https://img.shields.io/pub/v/objective_c.svg)](https://pub.dev/packages/objective_c) |
 | [swift2objc](pkgs/swift2objc/) | A tool for generating bindings that allow interop between Dart and Swift code. | [![issues](https://img.shields.io/badge/package:swift2objc-4774bc)][swift2objc_issues] | [![pub package](https://img.shields.io/pub/v/swift2objc.svg)](https://pub.dev/packages/swift2objc) |
 | [swiftgen](pkgs/swiftgen/) | A tool for generating bindings that allow interop between Dart and Swift code. | [![issues](https://img.shields.io/badge/package:swiftgen-4774bc)][swiftgen_issues] | [![pub package](https://img.shields.io/pub/v/swiftgen.svg)](https://pub.dev/packages/swiftgen) |
 
+[code_assets_issues]: https://github.com/dart-lang/native/issues?q=is%3Aissue+is%3Aopen+label%3Apackage%3Acode_assets
+[data_assets_issues]: https://github.com/dart-lang/native/issues?q=is%3Aissue+is%3Aopen+label%3Apackage%3Adata_assets
 [ffi_issues]: https://github.com/dart-lang/native/issues?q=is%3Aissue+is%3Aopen+label%3Apackage%3Affi
 [ffigen_issues]: https://github.com/dart-lang/native/issues?q=is%3Aissue+is%3Aopen+label%3Apackage%3Affigen
+[hooks_issues]: https://github.com/dart-lang/native/issues?q=is%3Aissue+is%3Aopen+label%3Apackage%3Ahooks
+[hooks_runner_issues]: https://github.com/dart-lang/native/issues?q=is%3Aissue+is%3Aopen+label%3Apackage%3Ahooks_runner
 [jni_issues]: https://github.com/dart-lang/native/issues?q=is%3Aissue+is%3Aopen+label%3Apackage%3Ajni
 [jnigen_issues]: https://github.com/dart-lang/native/issues?q=is%3Aissue+is%3Aopen+label%3Apackage%3Ajnigen
-[native_assets_builder_issues]: https://github.com/dart-lang/native/issues?q=is%3Aissue+is%3Aopen+label%3Apackage%3Anative_assets_builder
-[native_assets_cli_issues]: https://github.com/dart-lang/native/issues?q=is%3Aissue+is%3Aopen+label%3Apackage%3Anative_assets_cli
 [native_toolchain_c_issues]: https://github.com/dart-lang/native/issues?q=is%3Aissue+is%3Aopen+label%3Apackage%3Anative_toolchain_c
 [objective_c_issues]: https://github.com/dart-lang/native/issues?q=is%3Aissue+is%3Aopen+label%3Apackage%3Aobjective_c
 [swift2objc_issues]: https://github.com/dart-lang/native/issues?q=is%3Aissue+is%3Aopen+label%3Apackage%3Aswift2objc

.github/workflows/native.yaml

@@ -1,3 +1,8 @@
-## 0.1.0-wip
+## 0.19.0-wip
+
+- Split up `package:native_assets_cli` in `package:hooks`,
+  `package:code_assets`, and `package:data_assets`.
+
+## 0.1.0
 
 - Initial version.

CONTRIBUTING.md

@@ -6,11 +6,6 @@
 This library contains the hook protocol specification for bundling native code
 with Dart packages.
 
-## This package is documentation only for the moment.
-
-For using this feature, please refer to `package:native_assets_cli` for now.
-In the future, we'll split up that package into here.
-
 ## Status: Experimental
 
 **NOTE**: This package is currently experimental and published under the

README.md

@@ -3,12 +3,12 @@ These schemas document the protocol for build and link hooks with code assets.
 * If you are a hook author, you should likely be using a hook-helper-package
   Dart API (such as `package:native_toolchain_c`) instead of directly consuming
   and producing JSON.
-* If you are a hook-helper-package author, you should likely be using a
-  hook-helper-package's Dart API (such as `package:native_assets_cli`) which
-  abstracts away from syntactic changes. If you do want to directly interact
-  with the JSON, you can find the relevant schemas in [hook/](hook/).
+* If you are a hook-helper-package author, you should likely be using this
+  package's Dart API which abstracts away from syntactic changes. If you do want
+  to directly interact with the JSON, you can find the relevant schemas in
+  [hook/](hook/).
 * If you are an SDK author, you should likely be using the SDK helper package
-  (`package:native_assets_builder`) which abstracts away from syntactic changes.
+  (`package:hooks_runner`) which abstracts away from syntactic changes.
   If you do want to directly interact with the JSON, you can find the relevant
   schemas in [sdk/](sdk/).
 

pkgs/code_assets/CHANGELOG.md

@@ -100,11 +100,11 @@ extension ArchitectureSyntaxExtension on Architecture {
 
   ArchitectureSyntax toSyntax() => _toSyntax[this]!;
 
-  static Architecture fromSyntax(ArchitectureSyntax syntax) =>
-      switch (_fromSyntax[syntax]) {
-        null => throw FormatException(
-          'The architecture "${syntax.name}" is not known',
-        ),
-        final arch => arch,
-      };
+  static Architecture fromSyntax(
+    ArchitectureSyntax syntax,
+  ) => switch (_fromSyntax[syntax]) {
+    null =>
+      throw FormatException('The architecture "${syntax.name}" is not known'),
+    final arch => arch,
+  };
 }

pkgs/code_assets/README.md

@@ -23,9 +23,10 @@ final class CCompilerConfig {
 
   /// Configuration provided when [CodeConfig.targetOS] is [OS.windows].
   WindowsCCompilerConfig get windows => switch (_windows) {
-    null => throw StateError(
-      'Cannot access windows if CodeConfig.targetOS is not Windows',
-    ),
+    null =>
+      throw StateError(
+        'Cannot access windows if CodeConfig.targetOS is not Windows',
+      ),
     final c => c,
   };
 

pkgs/code_assets/doc/schema/README.md

@@ -2,8 +2,8 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
-import '../config.dart';
-import '../encoded_asset.dart';
+import 'package:hooks/hooks.dart';
+
 import 'config.dart';
 import 'link_mode.dart';
 import 'os.dart';