CLAUDE.md # flutter_rust_bridge Development Rules ## Rules ### Do not manually edit these auto-generated files | File Pattern | Description | |--------------|-------------| | `frb_generated.*` | Generated by `frb_codegen` - modify generator logic instead | | `*.freezed.dart` | Freezed output | | `*.g.dart` | Code generator output | ### PR size and complexity - When humans describe a PR as large or complex, generated code is excluded. - Keep implementations as simple as possible while preserving correctness. ### Feature flags When adding or testing feature flags, read `frb-feature-flag`. ## Skills - `frb-code-generation` - Which generation commands to run - `frb-develop-feature` - New feature development workflow - `frb-feature-flag` - Feature flag API surface and enabled/disabled coverage rules - `frb-test` - How to run tests - `frb-debugging` - Debug code generation issues - `frb-lint` - Lint and format checks - `frb-manual-test` - Manual regression test reports - `frb-prepare-pr` - PR preparation - `frb-fix-ci` - CI fixes - `frb-fix-main-ci` - Default-branch CI regression triage - `frb-docker` - Ordinary Docker/devcontainer usage and local validation - `frb-upgrade-docker` - Dev Docker toolchain upgrades, candidate images, and stable publication --- name: frb-add-contributor description: Add or reconcile flutter_rust_bridge contributors through all-contributors PRs. Use when finding contributor PRs, posting all-contributors comments, validating contributor metadata, resolving contributor PR merge conflicts, or merging the generated contributor PRs. --- # FRB Add Contributor Use this skill when contributors need to be added to `flutter_rust_bridge` via `all-contributors`, especially when multiple recent PR authors should be credited in batch. ## Step 1: Find the correct source PRs For each GitHub username, find their PRs in `fzyzcjy/flutter_rust_bridge`. ```bash gh search prs --repo fzyzcjy/flutter_rust_bridge --author --limit 100 --json number,title,author,url,state ``` Important: - Deduplicate by contributor. A single person may have multiple merged PRs. - If the task is about `new contributor PR`s, use the contributor's first PR only. - For release reconciliation, inspect every third-party human-authored PR in the same release range used by `frb-write-changelog`. - For each such PR, confirm that the contributor's human-written `.all-contributors-custom.yaml` summary covers that contribution. Being present in `.all-contributorsrc` or `README.md` is not sufficient. - Treat an existing contributor whose summary does not cover a release-range PR as needing reconciliation, but do not expect a new all-contributors PR for that person. - If the contributor already exists in `.all-contributorsrc` or `README.md`, do not expect a new all-contributors PR to be created. ## Step 2: Stop for human confirmation After determining which contributors may need to be added or have their custom descriptions extended, stop and ask a human to confirm the contributor list and source PRs before taking any mutating action. This stop is mandatory. - Do not edit `.all-contributors-custom.yaml`. - Do not regenerate contributor artifacts. - Do not post all-contributors comments. - Do not create or merge any PRs. - Do not perform any other GitHub mutation. Only continue after the human explicitly confirms which contributors to add or update and which source PRs those changes cover. ## Step 3: Prepare `.all-contributors-custom.yaml` and stop for human input Before regenerating contributor artifacts, append each new contributor to the end of `.all-contributors-custom.yaml`: ```yaml - : TODO ``` Do this only for contributors who are not already present in `.all-contributors-custom.yaml`. For an existing credited contributor with no custom entry, append: ```yaml - : TODO(#) ``` For an existing contributor whose summary does not cover a release-range PR, preserve the existing human-written text and append a marker for each uncovered PR: ```yaml - : TODO(#) ``` Then stop and ask a human to replace each `TODO` or `TODO(#)` with a concise contribution summary. This stop is mandatory. - Do not continue to Step 3 or any later step in this skill until the human has replaced every `TODO`. - Do not run contributor generation. - Do not post all-contributors comments. - Do not resolve or merge contributor PRs. Only resume after the human-written descriptions are present in `.all-contributors-custom.yaml`. ## Step 4: Trigger all-contributors Post the comment on the chosen source PR: ```bash gh pr comment --repo fzyzcjy/flutter_rust_bridge --body '@all-contributors please add for code' ``` Then inspect the bot response on that PR. - Skip this step for an existing contributor whose only gap was an incomplete custom description. - If the bot says the user already contributed before, stop there for that user. - Otherwise, wait for the bot to open a PR named `docs: add as a contributor for code`. ## Step 5: Validate contributor metadata When a contributor PR exists, check the generated contributor data before merging. Files to inspect: - `.all-contributorsrc` - `README.md` Required validation: - Homepage URLs must use `https://`, never `http://`. - If the generated homepage is `http://`, change it to `https://` if the site supports it. - If the personal site does not support `https://`, prefer the contributor's GitHub profile URL instead of keeping `http://`. ## Step 6: Regenerate contributor output After the human has replaced all `TODO` markers, confirm that the custom summaries cover every third-party release-range PR. Then regenerate the contributor artifacts instead of hand-editing `README.md`. Use: ```bash ./frb_internal generate-internal-contributor ``` This command updates: - `.all-contributorsrc` - `README.md` via `all-contributors generate` - `website/docs/index.md` via `generate-internal-readme` If you only need to refresh the website copy of the README, use: ```bash ./frb_internal generate-internal-readme ``` ## Step 7: Resolve merge conflicts in contributor PRs These PRs usually conflict only in: - `.all-contributorsrc` - `README.md` Recommended workflow for each open contributor PR: ```bash gh pr checkout --repo fzyzcjy/flutter_rust_bridge git fetch origin master git merge --no-ff origin/master ``` If the merge conflicts: 1. Keep the latest `origin/master` content. 2. Re-apply the contributor entry from the bot branch. 3. Ensure the contributor card remains present in `README.md`. 4. Re-run `./frb_internal generate-internal-contributor` if you edited contributor metadata or finished filling in `.all-contributors-custom.yaml`. 5. `git add` the resolved files and commit the merge. 6. Push the contributor branch back to origin. Do not revert unrelated contributor entries that were merged by other PRs. ## Step 8: Merge the contributor PRs After the branch is updated and GitHub reports it mergeable: ```bash gh pr merge --repo fzyzcjy/flutter_rust_bridge --merge --delete-branch ``` Notes: - GitHub may temporarily report `DIRTY` or reject merge immediately after push. - If that happens, wait briefly, re-check the PR state, and retry the merge. - After merging one contributor PR, fetch `origin/master` again before resolving the next one. ## Step 9: Final verification At the end, verify there are no remaining open all-contributors PRs: ```bash gh pr list --repo fzyzcjy/flutter_rust_bridge --search "author:allcontributors[bot] is:open" --limit 50 --json number,title,mergeStateStatus,url ``` Also verify the credited contributors appear in: - `.all-contributorsrc` - `README.md` - `website/docs/index.md` if contributor regeneration was run --- name: frb-android-emulator-prepare description: Use when preparing, installing, diagnosing, or explaining the host Android Emulator environment for flutter_rust_bridge local runtime validation, including Android SDK command-line tools, emulator packages, AVD creation, host emulator startup, and Docker-local ADB connectivity to the emulator TCP endpoint. --- # FRB Android Emulator Preparation Use this skill when a task requires a **host Android Emulator** for FRB local runtime validation. ## Boundary FRB Android runtime validation currently supports a host Android Emulator path: host needs Java, Android SDK command-line tools, `emulator`, a system image, and an AVD; Docker runs FRB/Flutter commands through a Docker-local ADB server connected to the emulator TCP endpoint. Do not install Android Emulator packages unless the user has explicitly asked to prepare or run an emulator. Installing the emulator changes host state and downloads large SDK packages. ## Default Host Locations Use standard Android Studio locations on macOS: ```text ~/Library/Android/sdk ~/.android/avd ~/.android ``` Respect `ANDROID_HOME` if it is already set. Otherwise use `~/Library/Android/sdk`. Do not invent repo-specific defaults such as `/workspace`, `/tmp`, or a user's personal artifacts directory. ## Preflight Official references for this workflow: - Android Studio and command-line tools download page: https://developer.android.com/studio - `sdkmanager` command-line package manager: https://developer.android.com/tools/sdkmanager - `avdmanager` command-line AVD manager: https://developer.android.com/tools/avdmanager - Android Emulator command line: https://developer.android.com/studio/run/emulator-commandline - ADB command-line tool: https://developer.android.com/tools/adb Run these before installing anything: ```bash sw_vers uname -m which adb || true adb version || true echo "${ANDROID_HOME:-}" ls -ld "$HOME/Library/Android/sdk" "$HOME/.android" "$HOME/.android/avd" 2>/dev/null || true which java || true java -version || true ``` If the task requires an emulator, record whether these tools already exist: ```bash ls "$HOME/Library/Android/sdk/cmdline-tools/latest/bin/sdkmanager" 2>/dev/null || true ls "$HOME/Library/Android/sdk/cmdline-tools/latest/bin/avdmanager" 2>/dev/null || true ls "$HOME/Library/Android/sdk/emulator/emulator" 2>/dev/null || true ``` ## Installation Policy Before installing or downloading anything, state exactly what will be installed and ask for approval through the command escalation mechanism. For a minimal macOS emulator setup, expect these host changes: ```text Homebrew openjdk, if Java is missing ~/Library/Android/sdk/cmdline-tools/latest ~/Library/Android/sdk/emulator ~/Library/Android/sdk/platform-tools ~/Library/Android/sdk/platforms/android- ~/Library/Android/sdk/system-images/android-/google_apis/arm64-v8a ~/.android/avd/.avd ~/.android/avd/.ini ``` Prefer ARM64 system images on Apple Silicon: ```text system-images;android-35;google_apis;arm64-v8a ``` Use a different API level only when the task or Flutter version requires it. ## Install Java If `/usr/bin/java` is missing and Homebrew is available, prefer the Homebrew `openjdk` formula because it does not require the sudo package installer: ```bash HOMEBREW_NO_AUTO_UPDATE=1 brew install openjdk ``` For SDK commands in the current shell, prepend the Homebrew JDK: ```bash export PATH="/opt/homebrew/opt/openjdk/bin:$PATH" ``` Do not use `brew install --cask temurin` in non-interactive agent runs unless the user has approved sudo-capable installation; it may invoke macOS Installer through `sudo`. ## Install Command-Line Tools If Android Studio is not installed and `cmdline-tools/latest` is missing, install the official Android command-line tools into the standard SDK root. This follows the Android Developers command-line tools instructions on the Android Studio download page: https://developer.android.com/studio. The important shape is to download the command-line tools package from that page, extract it, and place it under `cmdline-tools/latest` in the Android SDK root. ```bash mkdir -p "$HOME/Library/Android/sdk/cmdline-tools/latest" curl -L -o /private/tmp/commandlinetools-mac-latest.zip \ https://dl.google.com/android/repository/commandlinetools-mac-14742923_latest.zip mkdir -p /private/tmp/frb-android-commandlinetools-extract ditto -x -k /private/tmp/commandlinetools-mac-latest.zip /private/tmp/frb-android-commandlinetools-extract cp -R /private/tmp/frb-android-commandlinetools-extract/cmdline-tools/. \ "$HOME/Library/Android/sdk/cmdline-tools/latest/" ``` Then set: ```bash export ANDROID_HOME="$HOME/Library/Android/sdk" export ANDROID_SDK_ROOT="$ANDROID_HOME" export PATH="/opt/homebrew/opt/openjdk/bin:$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH" ``` ## Install Emulator Packages Accept licenses and install the minimal packages with `sdkmanager`, the Android SDK package manager documented by Android Developers at https://developer.android.com/tools/sdkmanager: ```bash yes | sdkmanager --licenses sdkmanager \ "emulator" \ "platform-tools" \ "platforms;android-35" \ "system-images;android-35;google_apis;arm64-v8a" ``` If the user wants a smaller or non-Google image, choose a matching `system-images;android-;default;arm64-v8a` package instead. ## Create AVD Use a predictable AVD name that the `frb-dev-env` examples can reference. This uses `avdmanager`, the Android Developers command-line tool for creating and managing AVDs documented at https://developer.android.com/tools/avdmanager: ```bash avdmanager create avd \ --name FRB_API_35 \ --package "system-images;android-35;google_apis;arm64-v8a" \ --device "pixel_8" ``` If the device profile is unavailable, list device profiles and choose a common phone: ```bash avdmanager list device ``` ## Start And Verify Emulator Start the host emulator through `frb-dev-env`. The underlying emulator invocation follows the Android Emulator command-line interface documented at https://developer.android.com/studio/run/emulator-commandline: ```bash .claude/skills/frb-dev-env/frb_dev_env.py android emulator --avd FRB_API_35 --port 5554 ``` Verify host ADB can see the emulator. This uses ADB, the Android Developers command-line tool documented at https://developer.android.com/tools/adb: ```bash adb devices -l ``` For emulator runtime tests, let Docker use its own ADB server and connect directly to the host emulator ADB TCP endpoint. For emulator console port `5554`, that endpoint is `host.docker.internal:5555`: ```bash .claude/skills/frb-dev-env/frb_dev_env.py docker exec --android-emulator-adb -- adb devices -l ``` Only after both ADB checks pass, run an FRB Android runtime command. Use the Docker-visible emulator serial: ```bash .claude/skills/frb-dev-env/frb_dev_env.py docker exec --android-emulator-adb -- \ bash -lc './frb_internal test-flutter-native --package frb_example--flutter_via_create --flutter-test-args "--device-id host.docker.internal:5555"' ``` ## Common Failures - `Android SDK root does not exist`: install Android Studio or command-line tools into `~/Library/Android/sdk`, or set `ANDROID_HOME`. - `emulator: command not found`: install the SDK `emulator` package and ensure `~/Library/Android/sdk/emulator` is on `PATH`. - No AVD found: create `FRB_API_35` with `avdmanager create avd`, or pass the existing AVD name to `android emulator --avd`. - Docker cannot see the host emulator through `--android-emulator-adb`: verify the host emulator is running on console port `5554`, verify host `adb devices -l` shows `emulator-5554`, then run `adb connect host.docker.internal:5555` inside Docker or retry the helper command. - Flutter integration test fails with a VM service or DDS connection refused on `127.0.0.1`: the command likely used a host ADB server against an emulator. Use `--android-emulator-adb` so `adb forward` binds inside Docker. ## Cleanup Stop the emulator from host ADB: ```bash adb -s emulator-5554 emu kill ``` Avoid deleting SDK packages or AVDs unless the user explicitly asks. --- name: frb-cargokit-dev description: Develop or update CargoKit for flutter_rust_bridge. Use when a bug or feature belongs in fzyzcjy/Cargokit, when updating the FRB CargoKit submodule pointers, or when preparing the paired CargoKit and FRB PRs that synchronize CargoKit changes into FRB integrate templates and examples. --- # FRB CargoKit Development ## Overview Use this skill when the actual fix belongs in the external `fzyzcjy/Cargokit` repository and FRB needs a follow-up PR that points its CargoKit submodules at the updated CargoKit branch or commit. The usual shape is two PRs: 1. A CargoKit PR with the real implementation. 2. An FRB PR that updates the two CargoKit submodule pointers and regenerates copied integrate outputs. Do not implement CargoKit behavior only in copied FRB example output. The source of truth is the CargoKit repository referenced by the template submodules. ## Source Locations FRB embeds CargoKit as git submodules in two template locations: - `frb_codegen/assets/integration_template/app/rust_builder/cargokit` - `frb_codegen/assets/integration_template/plugin/cargokit` Both submodules should normally point at the same CargoKit branch or commit for the same logical update. Downstream generated copies may appear under: - `frb_example/**/cargokit/**` - `frb_example/**/rust_builder/cargokit/**` Read `frb-cargokit` first if you need to classify an existing diff before deciding where the change belongs. ## Workflow ### 1. Prepare The CargoKit Change Work in `fzyzcjy/Cargokit` for the actual CargoKit implementation. 1. Create a CargoKit branch whose name is easy to reference from the FRB PR. 2. Implement the fix in CargoKit and run the relevant CargoKit checks from that repository. 3. Push the branch and open a CargoKit PR. 4. Keep the branch alive until the FRB PR has passed CI. If you are editing through an FRB submodule checkout, remember that commits belong to the nested CargoKit repository, not the outer FRB repository. Push the nested repository branch before updating the outer FRB submodule pointer. ### 2. Update FRB To Point At The CargoKit Branch In the FRB repository: 1. Initialize submodules if needed: ```bash git submodule update --init --recursive ``` 2. Fetch and check out the CargoKit branch or commit in both submodule checkouts: ```bash git -C frb_codegen/assets/integration_template/app/rust_builder/cargokit fetch origin git -C frb_codegen/assets/integration_template/app/rust_builder/cargokit checkout git -C frb_codegen/assets/integration_template/plugin/cargokit fetch origin git -C frb_codegen/assets/integration_template/plugin/cargokit checkout ``` 3. Stage the submodule pointer updates in the outer FRB repository: ```bash git add frb_codegen/assets/integration_template/app/rust_builder/cargokit git add frb_codegen/assets/integration_template/plugin/cargokit ``` 4. Confirm the outer FRB diff shows submodule pointer changes for both paths. Useful checks: ```bash git submodule status --recursive git diff --submodule ``` Do not leave one template submodule on the old CargoKit commit unless the app and plugin templates intentionally need different CargoKit revisions. ### 3. Regenerate FRB Integrate Outputs After changing either CargoKit submodule pointer, run: ```bash ./frb_internal precommit-integrate ``` This updates copied CargoKit output and platform scaffold files under `frb_example/**`. Those downstream diffs are expected when CargoKit files are copied from the updated template. Stage and commit the regenerated integrate output together with the submodule pointer update: ```bash git add frb_example frb_codegen/assets/integration_template git commit -m "Update CargoKit template pointers" ``` Then run the normal PR checks from `frb-prepare-pr`, especially: ```bash ./frb_internal lint --fix ``` Run focused tests when the CargoKit change affects a platform that can be exercised locally. Otherwise let FRB CI cover the platform matrix and use `frb-fix-ci` for failures. ### 4. Open The FRB PR The FRB PR should mention that CargoKit is intentionally pointed at the temporary CargoKit PR branch or commit. Keep the PR body empty if the local PR workflow requires it, but use GitHub comments when you need to leave coordination notes. Before asking for final review: 1. Wait for the FRB PR CI to pass with the temporary CargoKit pointer. 2. Ask reviewers to merge the CargoKit PR first. 3. Update the FRB submodule pointers from the temporary branch commit to the merged CargoKit commit on the canonical branch. 4. Rerun `./frb_internal precommit-integrate` if the CargoKit commit changed. 5. Push the refreshed FRB PR and wait for CI again. 6. Ask reviewers to merge the FRB PR. ## CI Failure Triage When FRB CI fails after a CargoKit update, classify the failure before editing: - CargoKit behavior failure: fix it in `fzyzcjy/Cargokit`, then update both FRB submodule pointers. - Missing integrate refresh: run `./frb_internal precommit-integrate` and commit the copied output. - Lint or formatting drift: run `./frb_internal lint --fix`. - Platform-specific FRB scaffold issue: fix the FRB integration template, then run `./frb_internal precommit-integrate`. Do not patch copied `frb_example/**/cargokit/**` files directly as the final fix. They should be produced from the updated CargoKit submodule and integrate templates. ## Related Skills - `frb-cargokit` - Understand CargoKit ownership and diff layers - `frb-code-generation` - Choose the correct generation command - `frb-prepare-pr` - Prepare an FRB PR - `frb-fix-ci` - Diagnose CI failures after the PR is opened --- name: frb-cargokit description: Explain how cargokit is sourced, copied, and analyzed inside flutter_rust_bridge. Use when working on `integration_template/**/cargokit`, `frb_example/**/cargokit`, integrate/generate output drift, or any diff that mentions cargokit and you need to identify the true source of truth before judging the change. --- # FRB Cargokit ## Overview Use this skill to avoid mixing together three different things: the external cargokit repository, the template submodule pointers in FRB, and copied cargokit files inside generated examples. The main job is to determine which layer a change belongs to before analyzing whether the change is correct. ## Mental Model There are two important cargokit forms inside FRB: 1. External source FRB depends on an external cargokit repository through git submodules under `frb_codegen/assets/integration_template/**/cargokit`. 2. Copied outputs FRB commands such as integrate/generate often copy concrete cargokit files into `frb_example/**/cargokit` or `frb_example/**/rust_builder/cargokit`. This means a large cargokit diff in examples often does not mean FRB designed a large new cargokit behavior. It may only mean a template or submodule change propagated into copied outputs. ## Source Of Truth Treat these paths as the source of truth when deciding cargokit behavior: - `frb_codegen/assets/integration_template/app/rust_builder/cargokit` - `frb_codegen/assets/integration_template/plugin/cargokit` Treat these paths as downstream copies unless the evidence shows otherwise: - `frb_example/**/cargokit/**` - `frb_example/**/rust_builder/cargokit/**` Do not start by judging copied example files in isolation. First determine which source submodule pointer or template content produced them. ## Synchronizing Copies Use `./frb_internal sync-cargokit-copies` to refresh checked-in Cargokit copies from the template submodules when those copies are not already regenerated by the integrate CI. The command mirrors the Rust integration template writer's Cargokit filtering and copied-file prelude. Do not add `flutter_via_create`, `flutter_via_integrate`, or `flutter_package` to this sync map; the integrate generation CI already recreates those examples from templates. The CI `Generate :: Internal` job runs this as part of `./frb_internal generate-internal --set-exit-if-changed --coverage`, so the normal generate-internal diff gate also catches Cargokit copy drift. If Cargokit copies drift, fix the source-of-truth template/submodule first when appropriate, run `./frb_internal sync-cargokit-copies`, and commit the resulting copied-output refresh. ## Diff Analysis Order When a user asks "what happened to cargokit?" follow this order: 1. Identify the layer. Decide whether the diff is a submodule pointer update, a template file change, or copied output churn. 2. If the change is a submodule pointer update, inspect the two external cargokit commits first. Compare the old and new submodule SHAs inside the submodule repository before saying anything about the FRB-side diff. 3. Only then inspect copied example files. Ask whether they merely reflect the upstream change or whether FRB also introduced independent local edits. 4. Separate semantic changes from churn. Distinguish real logic changes from format-only refreshes, lockfile updates, scaffold refreshes, and regenerated outputs. ## What To Say Explicitly When answering, state which of these is true: - "This is an external cargokit change exposed by a submodule pointer update." - "This is downstream copy churn caused by integrate/generate." - "This repository also has local copied cargokit edits in examples." If discussing correctness, tie the judgment to the correct layer: - For submodule updates, judge the diff between the two external SHAs. - For copied outputs, judge whether the copy is expected and synchronized. - Do not infer upstream intent from a regenerated example diff alone. ## Common Mistakes Avoid these mistakes: - Treating `frb_example/**/cargokit/**` as the primary implementation source. - Assuming a large example diff implies a large semantic cargokit change. - Analyzing copied files before checking the submodule pointer diff. - Mixing "FRB updated the pointer" with "FRB locally rewrote cargokit." ## Scope Boundary This skill explains ownership, propagation, and diff interpretation. Use `frb-code-generation` when you need to know which generation command to run. Use `frb-debugging` when generation or cargokit-related behavior is failing and needs deeper investigation. --- name: frb-categorize-code-diff description: Use when classifying a flutter_rust_bridge branch or PR diff into test and non-test changes, including colocated Rust test modules. --- # 1 When to use - Use this skill to answer which changes in a branch or PR are tests and which are not. - Use the repository script instead of classifying paths by hand. Rust tests are commonly colocated in production `.rs` files. ## 2 Run - Fetch the PR base before relying on `origin/master`. - Run from the repository root: ```bash uv run --no-project .claude/skills/frb-categorize-code-diff/categorize_code_diff.py --base origin/master --head HEAD ``` - Add `--json` when another tool will consume the result. - Pass the PR's actual base revision when it is not `origin/master`. ## 3 Interpret - `test-only`: every changed line is in a dedicated test path or a recognized colocated Rust test region. - `non-test-only`: every changed line is outside recognized test code. - `mixed`: the file contains both test and non-test changed lines. - `unclassified`: the diff cannot be mapped confidently, such as a binary patch. - Treat the non-test list as conservative. Unknown code is non-test rather than silently counted as test. ## 4 Reliability - The script compares `base...head`, matching GitHub pull request diff semantics. - Dedicated test paths include `test/`, `tests/`, `test_fixtures/`, and conventional test filenames. - Rust inline classification recognizes brace-delimited items preceded by `#[cfg(test)]` or `#[test]` in both the base and head revisions. - Re-run after every PR update. Line identities and rename targets may change. - Inspect `mixed` files manually before claiming that a PR contains no production changes. ## 5 Validation - Run the script tests after changing its classification logic: ```bash PYTHONDONTWRITEBYTECODE=1 uv run --no-project --with pytest --with typer pytest -q .claude/skills/frb-categorize-code-diff/test_categorize_code_diff.py ``` - Keep `PYTHONDONTWRITEBYTECODE=1`; otherwise pytest leaves an untracked `__pycache__/` inside the skill directory. --- name: frb-ci-filter description: Use when running focused flutter_rust_bridge GitHub Actions CI via ci_filter, adding/removing the ci-manual-dispatch PR label, choosing exact CI jobs or matrix entries, documenting intentionally partial CI runs, or repeatedly validating an exact CI target on one commit. --- Use this skill when CI feedback is too expensive and the current task needs a focused GitHub Actions signal instead of automatic full CI. The preferred mechanism is the formal `workflow_dispatch` input in `.github/workflows/ci.yaml`: ```bash gh workflow run ci.yaml --ref -f 'ci_filter=' ``` Do not temporarily hack workflow jobs just to get partial CI unless the formal filter cannot express the target. # 1 Filter Syntax ```text full job_id job_a,job_b job_id[dimension=value] job_id[dimension=value|other_value,other_dimension=value] job_a,job_b[dimension=value] ``` - `full` or `*` runs the normal full CI plan. - `job_id` runs the whole job, including its full matrix if it has one. - `job_id[...]` runs only matching matrix entries. - Bracket filters currently require `dimension=value`. - Commas outside brackets combine multiple jobs. - Explicit `dimension=value` conditions inside brackets are ANDed. - `|` means OR within one dimension. - Matrix dimensions include direct keys such as `image`, `package`, `device`, `api-level`, `sanitizer`, `platforms`, and nested `matrix.info` keys such as `platform`, `target`, `version`. - Numeric matrix values are matched as strings, e.g. `api-level=35`. - Values may contain spaces, e.g. iOS simulator device names. - Unknown jobs, unknown dimensions, malformed filters, and filters matching no matrix entries fail in the `Plan :: CI` job. # 2 Manual Dispatch Label Use the `ci-manual-dispatch` PR label when an agent or human wants to prevent automatic PR CI from running the full surface while iterating. ```bash gh pr edit --add-label ci-manual-dispatch ``` With the label present: - normal PR-triggered CI produces an empty plan for the heavy jobs - `workflow_dispatch` remains available for explicit focused runs - the PR must not be treated as merge-ready from partial runs alone Before final readiness: ```bash gh pr edit --remove-label ci-manual-dispatch ``` Then let the normal full CI surface run. Removing the label triggers PR CI because the workflow listens to `labeled` and `unlabeled` pull request events. # 3 Manual Dispatch PR Comment Manual `workflow_dispatch` runs of `.github/workflows/ci.yaml` comment from `Plan :: CI` on the matching open PR with the selected `ci_filter` and run link; normal `push` and `pull_request` runs do not comment. # 4 Local Planning Before dispatching an expensive manual run, smoke the filter locally: ```bash ./frb_internal plan-ci --filter 'test_dart_web[package=frb_example--pure_dart_pde]' ``` The command emits a GitHub Actions output line: ```text plan={...} ``` The workflow consumes it with paths like: ```yaml fromJSON(needs.plan_ci.outputs.plan).test_dart_web.enable fromJSON(needs.plan_ci.outputs.plan).test_dart_web.matrix ``` That output shape is intentional; each CI job has its own top-level entry containing `enable`, and matrix jobs also contain `matrix`. # 5 Repeated Precise Validation Use repeated precise validation when a flaky fix needs several independent executions of one CI job or matrix entry on exactly the same commit. - **Fix the commit**: Push the branch once, record its SHA, and do not move the branch until all runs finish. - **Smoke the filter**: Run `./frb_internal plan-ci --filter ''` before dispatching. - **Dispatch independently**: Create five separate `workflow_dispatch` runs, not one run with five matrix copies and not five attempts of one run. - **Keep the filter identical**: Pass the same exact `ci_filter` to every dispatch. - **Verify the SHA**: Confirm every selected run reports the recorded `headSha`; a branch name alone is not evidence that queued runs used the same commit. - **Count target jobs**: Count the conclusion of the selected job or matrix entry, not the workflow conclusion or skipped jobs. - **Preserve every run link**: Report all five run URLs, the fixed SHA, the filter, and the target-job result. - **Do not move or cancel**: A new commit invalidates the comparison; cancellation does not count as a completed validation. Record the immutable input: ```bash branch=codex/example-fix expected_sha=$(git rev-parse HEAD) filter='test_dart_web[package=frb_example--pure_dart]' git push -u origin "$branch" ``` Dispatch five independent runs. Manual dispatches use unique concurrency groups, so these runs do not cancel one another: ```bash for run_number in 1 2 3 4 5; do gh workflow run ci.yaml --ref "$branch" -f "ci_filter=$filter" done ``` List the candidate runs once, then select the five runs created for this validation window: ```bash gh run list \ --workflow ci.yaml \ --branch "$branch" \ --event workflow_dispatch \ --limit 10 \ --json databaseId,createdAt,headSha,status,conclusion,url ``` For each selected run: - Confirm `headSha == expected_sha`. - Confirm `Plan :: CI` creates only the requested job or matrix entry. - Wait for the target job to complete. - If it fails, archive and inspect that job's complete log. - Report a result only after all five target jobs finish. Do not claim “5/5” from any of these shapes: - One workflow run containing five matrix entries. - One workflow run rerun five times. - Five workflow runs whose `headSha` values differ. - Five workflow conclusions where the target job was skipped, cancelled, or never started. - Fewer than five completed target jobs plus queued or in-progress jobs. # 6 Examples These examples are protected by `tools/frb_internal/test/ci_plan_test.dart`; update that test whenever adding or changing examples here. Full CI: ```bash gh workflow run ci.yaml --ref -f 'ci_filter=full' ``` One non-matrix job: ```bash gh workflow run ci.yaml --ref -f 'ci_filter=lint_dart_primary' ``` Several whole jobs: ```bash gh workflow run ci.yaml --ref -f 'ci_filter=lint_dart_primary,test_dart_web' ``` One non-matrix job plus one matrix entry: ```bash gh workflow run ci.yaml --ref -f 'ci_filter=lint_dart_primary,test_dart_web[package=frb_example--pure_dart]' ``` One Dart web package: ```bash gh workflow run ci.yaml --ref -f 'ci_filter=test_dart_web[package=frb_example--pure_dart_pde]' ``` Two Dart web packages: ```bash gh workflow run ci.yaml --ref -f 'ci_filter=test_dart_web[package=frb_dart|frb_example--pure_dart_pde]' ``` Two Dart web packages plus one non-matrix job: ```bash gh workflow run ci.yaml --ref -f 'ci_filter=test_dart_web[package=frb_dart|frb_example--pure_dart_pde],lint_rust_primary' ``` Two precise matrix tuples in the same job: ```bash gh workflow run ci.yaml --ref -f 'ci_filter=test_rust[image=ubuntu-latest,version=nightly],test_rust[image=ubuntu-latest,version=1.85.0]' ``` One Dart native package on Linux: ```bash gh workflow run ci.yaml --ref -f 'ci_filter=test_dart_native[image=ubuntu-24.04,package=tools--frb_internal]' ``` Rust tests on selected toolchains: ```bash gh workflow run ci.yaml --ref -f 'ci_filter=test_rust[image=ubuntu-latest,version=nightly|1.85.0]' ``` One Flutter desktop package on Linux: ```bash gh workflow run ci.yaml --ref -f 'ci_filter=test_flutter_native_desktop[platform=linux,package=frb_example--gallery]' ``` One Android emulator matrix entry: ```bash gh workflow run ci.yaml --ref -f 'ci_filter=test_flutter_native_android[package=frb_example--flutter_via_create,device=pixel,api-level=35]' ``` One iOS simulator matrix entry: ```bash gh workflow run ci.yaml --ref -f 'ci_filter=test_flutter_native_ios[device=iPhone 16 Pro Max Simulator (18.6),package=frb_example--rust_ui_counter--ui]' ``` One codegen command-generate entry: ```bash gh workflow run ci.yaml --ref -f 'ci_filter=generate_run_frb_codegen_command_generate[image=ubuntu-24.04,package=frb_example--integrate_third_party]' ``` One OHOS command-integrate entry: ```bash gh workflow run ci.yaml --ref -f 'ci_filter=generate_run_frb_codegen_command_integrate[platforms=ohos]' ``` One sanitizer entry: ```bash gh workflow run ci.yaml --ref -f 'ci_filter=test_dart_sanitizer[sanitizer=asan,package=frb_example--pure_dart]' ``` One benchmark runner: ```bash gh workflow run ci.yaml --ref -f 'ci_filter=bench_dart_native[image=ubuntu-24.04]' ``` # 7 Choosing Evidence For intentional red reproduction PRs: - Run only the single job or matrix entry that proves the reported bad behavior. - State the exact `ci_filter` in the PR body. - State the expected failure text or behavior. - Do not treat the narrowed red run as fix readiness evidence. For ordinary iteration branches: - Prefer the smallest filter that exercises the changed behavior. - Say in PR status/comments when only filtered CI has run. - Before final review or merge readiness, remove `ci-manual-dispatch` and run normal CI. # 8 Validation Before pushing changes to the filter mechanism or examples: ```bash cd tools/frb_internal dart test test/ci_plan_test.dart ``` Useful smoke check: ```bash ./frb_internal plan-ci --filter 'test_dart_web[package=frb_example--pure_dart_pde]' ``` --- name: frb-code-generation description: Use when modifying Rust APIs, codegen, generated examples, or platform scaffolds in flutter_rust_bridge to select generation commands and preserve source-of-truth and convergence rules --- # FRB Code Generation > **Note:** Read `frb-dev-env` before running commands and follow the active user's environment rules. ## Overview flutter_rust_bridge requires code generation when Rust APIs change. This skill maps change types to the minimal generation commands needed. **Core principle:** Run only the generation commands needed for your change type. **Validation rule:** If regenerated outputs cause previously green non-`Generate` jobs to fail, treat the generated outputs as suspect until they are validated from a clean environment. > **After codegen:** Follow `frb-dev-env` and verify generated output is present in the selected worktree before reviewing the diff. ## Quick Reference | Change Type | Command | |-------------|---------| | Example Rust API (`frb_example/**/rust/src/api/*.rs`) | `./frb_internal precommit-generate` | | Flutter integrate examples | `./frb_internal precommit-integrate` | | `frb_codegen/` generation logic | `./frb_internal precommit-generate` + `generate-internal-rust` | | `frb_rust/src/` core API | `./frb_internal generate-internal-rust` | | `frb_example/pure_dart` generator | `./frb_internal generate-internal-frb-example-pure-dart` | | CLI help documentation | `./frb_internal generate-internal-book-help` | | Root `README.md` or `CHANGELOG.md` | `./frb_internal generate-internal-readme` | | Other non-generated docs, comments, tests, or `frb_dart/` source | No generation needed | ## Important Rules ### Root Documentation Fan-Out Treat the root `README.md` and `CHANGELOG.md` as sources of truth. After changing either file, run: ```bash ./frb_internal generate-internal-readme ``` Commit the generated package documentation in the same change. Do not manually edit `frb_dart/README.md`, `frb_dart/CHANGELOG.md`, or `frb_hooks/CHANGELOG.md`. ### Integrate Template Drift If a diff touches Flutter integrate example outputs, platform scaffolds, or copied `cargokit` files under `frb_example/**`, check whether the real source of truth should also change under `frb_codegen/assets/integration_template/`. Do not submit only downstream integrate output changes when the behavior belongs in the template. Update the template first, then run: ```bash ./frb_internal precommit-integrate ``` Treat `frb_codegen/assets/integration_template/**/cargokit` as the source of truth for copied `cargokit` output. If the actual bug belongs inside the external `cargokit` submodule, read the `frb-cargokit` skill before deciding whether to patch the submodule and update its pointer. For CI diagnosis rules about generated-file format/lint failures, repeated package-level `Generate` drift, or `Generate :: FRB Codegen :: Command Integrate` failures, you MUST read `frb-fix-ci` first. This skill is for command selection, not CI failure-propagation diagnosis. For `pure_dart` / `pure_dart_pde` generation issues, treat `frb_example/pure_dart` as the upstream source and `frb_example/pure_dart_pde` as the derived copy. See `frb-fix-ci` for the CI diagnosis workflow. If CI repair has already entered repeated package-level drift, you MUST stop choosing narrower commands and switch to `frb-fix-ci`. Do not manually patch generated files as the final fix. The final accepted result should be produced by the corresponding generation command in a clean matching environment. ### Generation Convergence - Run the narrowest owning generator before broad generation. - Normalize the intended source inputs, resolve dependencies, run final code generation, and format with the target toolchain. Do not hand formatter-unstable intermediate text to a different generation lane. - Run the owning generation command a second time and require a clean diff. A single successful run is not convergence. - Preserve semantic equivalence in templates. Do not move construction, scope, lifetime, or callback boundaries merely to make new formatter output look smaller. ### Generated Output Provenance Classify every changed path before accepting generated drift: | Provenance | Required action | | --- | --- | | Integration template | Change the template source and regenerate consumers | | Apple scaffold asset | Refresh through the owning scaffold workflow | | CargoKit copy | Read `frb-cargokit` and follow its ownership and synchronization rules | | Generated example output | Keep the generator and snapshot together | | Flutter migrator edit in a legacy example | Apply the exact current scaffold migration and record it as direct | | Unexplained manual edit | Revert it or identify its owning source before proceeding | - When an old example has no supported regeneration entry point, compare it with a fresh target-Flutter scaffold and directly apply only required tool-defined migrations. - Record direct legacy scaffold migrations separately from automatic output. ### OHOS Integrate Composition - Treat the checked-in package and the older OHOS Flutter fork as two distinct sources of truth. - Generate generic Flutter scaffold files with the current Flutter package. - Overlay only explicit OHOS-owned paths from the OHOS fork: `ohos` and, when required by the package, `rust_builder/ohos` and `rust_builder/pubspec.yaml`. - Exclude transient trees such as `node_modules` and preserve intentional deletions instead of resurrecting stale files. - Stage and validate the composed result before replacing the canonical package. Restore the original package if create, dependency resolution, code generation, formatting, or the final swap fails. - Test both success and failure paths. Do not add production APIs whose only purpose is exposing internals to tests. --- name: frb-debugging description: Use when generated code looks wrong, code generation fails, or you need to understand FRB internals --- # FRB Debugging > **Note:** Read `frb-dev-env` before running commands and follow the active user's environment rules. ## When to Use - Generated code looks wrong - Code generation fails - Need to understand FRB internals - Runtime errors in generated code ## Quick Diagnostics ### Dump Intermediate Representations The in-tree examples by default enable `dump_all: true` in `flutter_rust_bridge.yaml` for debugability. Therefore, you can check `rust/target/frb_dump/` for: - Effective configuration - IR (intermediate representation) - Generated spec and code - ... ### Debug Logs ```bash RUST_LOG=debug flutter_rust_bridge_codegen ... ``` ## Full Troubleshooting If above doesn't help, see: * `website/docs/docs/guides/contributing/tip.md` * `website/docs/manual/troubleshooting.md` Before going deep into FRB internals, first check whether you are actually seeing failure propagation from unstable generated outputs or integrate templates. In particular: - If CI failures may be explained by failure propagation, repeated package-level drift, or unstable generated outputs, you MUST use `frb-fix-ci` first - You MUST only stay in `frb-debugging` after `frb-fix-ci` has ruled out those simpler explanations ## Related Skills - `frb-code-generation` - Which generation commands to run - `frb-fix-ci` - Diagnose CI failure propagation before deep debugging - `frb-develop-feature` - Development workflow --- name: frb-dev-env description: "Use when the user wants Docker-based FRB development or Tart-based iOS Simulator validation." --- # FRB Development Environment Use this skill before setting up, diagnosing, or running `flutter_rust_bridge` commands with a container-based development workflow. ## Choosing an Environment Use Docker for normal FRB development checks that fit Linux containers: Rust tests, Dart tests, web tests, code generation, lint, Android build checks that do not need a running emulator, and most `./frb_internal` commands. Docker is the default reproducible baseline when local host toolchains are missing or suspected to have drifted. Use a host Android Emulator for local Android runtime validation when a running Android target is required. Keep FRB, Flutter, Rust, Gradle, and Android build tooling inside Docker. The host runs only the emulator and the Android SDK command-line tools needed to manage it. Docker runs its own ADB server and connects directly to the emulator TCP endpoint so Flutter's VM service forwarding stays inside Docker. See the Android section below. Use Tart only for checks that need macOS and Xcode, especially iOS Simulator validation. The Tart workflow is intentionally separate from Docker; it gives each worktree a reusable macOS VM cloned from a prepared base VM, then runs FRB commands inside that VM. Do not use the Tart macOS VM as the Android emulator strategy. macOS Tart guests do not support nested virtualization, so Android emulator runtime coverage needs a host or runner with virtualization support. Android SDK compilation checks can still use Docker when they do not need a running emulator. ## Principles - FRB runs locally in Docker by default. Do not use remote workspaces for FRB unless the user explicitly asks for a one-off remote run. - Use the current checkout/worktree that Codex or the user already selected. Do not create a new worktree unless the user explicitly asks. - Run FRB commands from the repository root unless the command itself intentionally changes directories. - Prefer repository tooling such as `./frb_internal` over ad hoc direct invocations. - Do not manually edit generated files (`frb_generated.*`, `*.freezed.dart`, `*.g.dart`) as the final fix. ## PATH Bootstrap Before using this skill's helper or FRB tooling, make sure common local tool locations are in `PATH`. Codex shells may start with a reduced `PATH`, which can hide `uv`, Docker, Dart, Flutter, or Homebrew-installed tools even when they exist on the machine. Use this prefix when a command reports `env: uv: No such file or directory`, `docker: command not found`, `dart: command not found`, or similar: ```bash export PATH="$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:$PATH" ``` Then retry the same command. Prefer fixing `PATH` over bypassing the helper, because `frb_dev_env.py` uses the configured per-worktree container and release credential handling. ## First Checks Before running tests, lint, code generation, or setup: ```bash git rev-parse --show-toplevel git status --short git submodule status --recursive ``` If submodules are uninitialized, initialize them locally: ```bash git submodule update --init --recursive ``` ## Docker Use Docker for container-based FRB development. Each worktree should have one long-lived local container that is reused for tests, lint, code generation, and setup commands. Use `frb_dev_env.py` next to this skill to inspect, create, start, and reuse the per-worktree container. The script derives the container name from the canonical worktree root only: ```text frb- ``` It mounts the canonical worktree root and git common root at their host-like absolute paths, and labels the container with: ```text frb.dev.repo=flutter_rust_bridge frb.dev.worktree= frb.dev.git-common-root= frb.dev.layout-version=3 ``` Commands run from the host-like worktree path inside the container. There is intentionally no `/workspace` alias, because linked git worktrees and submodule gitdir references need the same path shape that they have on the host. When creating a new per-worktree container, the helper pulls the selected Docker image before `docker run`. Existing containers are validated and reused without pulling. Typical usage: ```bash .claude/skills/frb-dev-env/frb_dev_env.py docker info .claude/skills/frb-dev-env/frb_dev_env.py docker create .claude/skills/frb-dev-env/frb_dev_env.py docker exec -- bash -lc './frb_internal --help' ``` ### Temporary Docker Commands With Publish Credentials Use `docker-run-rm --with-publish-credentials` only for release publishing commands that need host credentials. Unlike the normal long-lived development container, this runs a fresh temporary container with `docker run --rm`, mounts the worktree and git common root, mounts the host credential directories read-only, copies the credential files into temporary container-local homes, checks login status, runs the requested command, then discards the container. The publish credential flag mounts these host credential sources when present: - GitHub CLI config from `GH_CONFIG_DIR` or `~/.config/gh` - GitHub token env vars from `GH_TOKEN` or `GITHUB_TOKEN`, forwarded without printing token values - Cargo credentials and config from `CARGO_HOME` or `~/.cargo` - Git config from `~/.gitconfig` and `~/.config/git` - Dart pub credentials from `PUB_CACHE`, `~/.pub-cache`, `~/.config/dart`, or `~/Library/Application Support/dart` Publish mode also prepares the container environment used by the release command: - Reuses the Docker image's Rust toolchain via `RUSTUP_HOME=/root/.rustup` even though `HOME` is changed to a temporary credential directory. - Rewrites copied Git/Cargo config proxy URLs from `localhost` or `127.0.0.1` to `host.docker.internal`, and forwards common proxy environment variables with the same rewrite. This lets a container use a host proxy such as `http://localhost:7897`. - Checks GitHub auth, GitHub network access, Cargo availability, crates.io search access, and Dart pub credential readability before running the requested command. Run the credential preflight before any irreversible release step: ```bash .claude/skills/frb-dev-env/frb_dev_env.py docker-run-rm --with-publish-credentials -- true ``` Run release publishing through a temporary publish-credential container. Do not manually add `RUSTUP_HOME` or proxy environment overrides unless debugging the helper itself: ```bash .claude/skills/frb-dev-env/frb_dev_env.py docker-run-rm --with-publish-credentials -- ./frb_internal release ``` The credential preflight fails before running release commands if host GitHub CLI auth is invalid, Cargo credentials are missing, Dart pub credentials are missing, the image has no usable Cargo toolchain, or the container cannot reach GitHub/crates.io through the configured network path. It then re-checks GitHub CLI auth inside the temporary container and runs `gh auth setup-git` there so HTTPS `git push` can use the mounted GitHub CLI auth. ### Cleanup Delete a worktree's Docker container when the worktree is no longer needed, or when local Docker resources are getting crowded: ```bash .claude/skills/frb-dev-env/frb_dev_env.py docker delete ``` The delete command validates the container labels before removing it. Use `--force` only when intentionally removing a mismatched container. Use the project `frb-docker` skill for image, devcontainer, and Dockerfile details. ## Android Host Runtime Use this workflow for local Android runtime checks when Docker can build and run the FRB/Flutter command, but the Android target itself must be managed by the host. ### Path Selection The supported Android runtime path is: ```text host Android Emulator: host runs the emulator process Docker runs FRB/Flutter and its own ADB server Docker ADB connects to host.docker.internal: ``` Physical Android phones are intentionally out of scope for this helper until that path is manually validated. The host does not need FRB, Flutter, Rust, Cargo, Java, or Gradle for the emulator path. ### Host Emulator Architecture Use this split for a host Android Emulator: ```text host: Android Emulator process Android SDK command-line tools for SDK packages, AVD creation, emulator start/stop, and host-side inspection Android SDK root: ~/Library/Android/sdk unless ANDROID_HOME is set AVD root: ~/.android/avd Docker container: FRB checkout Flutter, Dart, Rust, Cargo, Java, Gradle Android SDK/NDK/build tools needed for builds Docker-local ADB server connected to host.docker.internal: ``` Read the project `frb-android-emulator-prepare` skill before preparing a host emulator. The host emulator path needs Java, Android SDK command-line tools, emulator packages, a system image, and an AVD in the standard Android Studio host locations. Print the resolved host Android SDK environment if needed: ```bash .claude/skills/frb-dev-env/frb_dev_env.py android env ``` Start the emulator on the host. Pin the port when you want a stable host serial such as `emulator-5554`; the paired emulator ADB TCP endpoint is one port higher, such as `host.docker.internal:5555`: ```bash .claude/skills/frb-dev-env/frb_dev_env.py android emulator --avd FRB_API_35 --port 5554 ``` Verify Docker-local ADB can see the host emulator: ```bash .claude/skills/frb-dev-env/frb_dev_env.py docker exec --android-emulator-adb -- adb devices -l ``` Run the FRB/Flutter command against the Docker-visible emulator serial: ```bash .claude/skills/frb-dev-env/frb_dev_env.py docker exec --android-emulator-adb -- \ bash -lc './frb_internal test-flutter-native --package frb_example--flutter_via_create --flutter-test-args "--device-id host.docker.internal:5555"' ``` `docker exec --android-emulator-adb` first runs `adb connect host.docker.internal:5555` inside the container, then runs the requested command with the Android SDK x86_64 runtime library path set. Override the default endpoint with `--android-emulator-adb-host`, `--android-emulator-adb-port`, `FRB_ANDROID_EMULATOR_ADB_HOST`, or `FRB_ANDROID_EMULATOR_ADB_PORT`. ### Why Emulator Does Not Use Host ADB Server Do not use a host ADB server for host emulator full Flutter integration tests. Flutter creates dynamic VM service `adb forward` ports where the ADB server runs. If the ADB server runs on the host, those forwarded ports bind on host `127.0.0.1`, but Flutter is running inside Docker and then tries Docker-local `127.0.0.1`. This fails with DDS or VM service connection refused errors. Use `--android-emulator-adb` so the ADB server and the forwarded VM service port both live inside Docker. ### Security And Cleanup - Use a single Android target when possible. With multiple emulators or devices, always pass `--device-id ` through `--flutter-test-args`. - For host emulator Flutter integration tests, use `--android-emulator-adb` so `adb forward` creates VM service forwarding inside Docker. - Do not run the Android Emulator inside Tart. Do not rely on Docker nested virtualization for Android emulator runtime checks on macOS. - If the Docker image lacks Android SDK, NDK, or build-tools packages required by Flutter Android builds, update the FRB Docker image or mount a dedicated Android SDK into the container; do not install host Flutter or Gradle just to work around the missing container toolchain. ## Tart Use Tart for iOS Simulator validation when Docker cannot provide the required macOS/Xcode runtime. The script uses one reusable Tart VM per worktree, named from the canonical worktree root: ```text frb-tart- ``` ### Base VM By default, `create` clones from a prepared local base VM named `frb-tart-base`. Override it with `FRB_TART_BASE_VM` or `--base-vm`. Read `frb-tart-prepare` before creating or changing the base VM. The base VM should be built by the checked-in Packer template from a pinned Tart OCI artifact and treated as immutable; do not boot it and manually install tools into it. ### Mounted Checkout For linked git worktrees, the Tart helper shares both the canonical worktree root and the git common root into the VM, then mounts them at host-like absolute paths with `mount_virtiofs`. This keeps worktree `.git` files and submodule gitdir references valid inside the VM. Use plain `tart exec` for light commands that should see the mounted host checkout exactly, such as `git status`, `flutter --version`, `xcrun simctl list`, and simulator boot commands. ### VM Lifecycle Inspect, create, start, and run light commands in the per-worktree VM: ```bash .claude/skills/frb-dev-env/frb_dev_env.py tart info .claude/skills/frb-dev-env/frb_dev_env.py tart create .claude/skills/frb-dev-env/frb_dev_env.py tart start .claude/skills/frb-dev-env/frb_dev_env.py tart ip --wait 180 .claude/skills/frb-dev-env/frb_dev_env.py tart exec -- sw_vers ``` ### Tart Guest Network Proxy When the Tart guest needs outbound network access through the host proxy, make the proxy listen on the host's Tart bridge address and pass that URL through the helper. Enable LAN access for the host proxy, keep the mixed proxy port at `7897`, and verify the host listens on `*:7897` rather than only `127.0.0.1:7897`. Tart guests normally reach the host on `192.168.64.1`, so the usual proxy URL is: ```bash export FRB_TART_HOST_PROXY_URL=http://192.168.64.1:7897 .claude/skills/frb-dev-env/frb_dev_env.py tart exec -- curl -I https://pub.dev ``` You can also pass the proxy for a single command: ```bash .claude/skills/frb-dev-env/frb_dev_env.py tart exec \ --host-proxy-url http://192.168.64.1:7897 \ -- curl -I https://pub.dev ``` Delete the worktree VM when it is no longer needed: ```bash .claude/skills/frb-dev-env/frb_dev_env.py tart stop .claude/skills/frb-dev-env/frb_dev_env.py tart delete ``` ### VM-Local Copy For heavy iOS build/test commands, prefer uploading the current worktree to a VM-local copy and running there. This avoids writing Xcode build artifacts through the virtiofs host mount: ```bash .claude/skills/frb-dev-env/frb_dev_env.py tart upload .claude/skills/frb-dev-env/frb_dev_env.py tart exec --sync-code -- ./frb_internal test-flutter-native --flutter-test-args '--device-id ' --package ``` `tart upload` and `tart exec --sync-code` both first ensure the worktree VM is running and the host-like worktree mount exists. They then run `rsync` inside the VM from the mounted host worktree to a VM-local copy under `/Users/admin/frb-dev-env-local-copies/`. The upload excludes `.git`, `.dart_tool`, `build`, `target`, `.idea`, and `.vscode`. It does not delete existing files in the VM-local copy, so build caches survive repeated runs. Commands run with `--sync-code` start from the VM-local uploaded copy, not from the host-mounted path. Examples: ```bash # Show the VM-local path after uploading the current worktree. .claude/skills/frb-dev-env/frb_dev_env.py tart upload # Run a heavy command from the uploaded VM-local copy. .claude/skills/frb-dev-env/frb_dev_env.py tart exec --sync-code -- ./frb_internal test-flutter-native --package frb_example--flutter_via_create --flutter-test-args '--device-id ' ``` ### iOS Integration Preparation Before running iOS Simulator integration tests, prepare the VM Flutter SDK once per VM or after replacing Flutter. This applies the runtime portion of `https://github.com/flutter/flutter/pull/187643.patch` as an idempotent Flutter tool workaround for an iOS simulator VM Service discovery race where `simctl launch` can emit the Dart VM Service log before Flutter's `simctl log stream` listener is ready. The preparation command also rebuilds `flutter_tools.snapshot`: ```bash .claude/skills/frb-dev-env/frb_dev_env.py tart prepare-ios-integration-test ``` Use the environment shown in the test command below for the integration test. `FLUTTER_GIT_URL` keeps `flutter doctor` and Flutter metadata consistent when the VM uses a local Flutter checkout. `FRB_SKIP_FLUTTER_DOCTOR=1` skips the FRB wrapper's preflight doctor because the simulator integration test itself is the validation target and doctor can hang after printing device checks in Tart. ### iOS Integration Test Run iOS Simulator tests by starting the worktree VM, preparing the VM Flutter SDK, choosing and booting an iOS simulator inside the VM, then running the existing FRB test command from the VM-local uploaded copy: ```bash .claude/skills/frb-dev-env/frb_dev_env.py tart start --wait 300 .claude/skills/frb-dev-env/frb_dev_env.py tart prepare-ios-integration-test .claude/skills/frb-dev-env/frb_dev_env.py tart exec -- xcrun simctl list devices available .claude/skills/frb-dev-env/frb_dev_env.py tart exec -- xcrun simctl boot .claude/skills/frb-dev-env/frb_dev_env.py tart exec -- xcrun simctl bootstatus -b .claude/skills/frb-dev-env/frb_dev_env.py tart exec --sync-code -- bash -lc 'export FLUTTER_GIT_URL=file:///Users/admin/flutter; export FRB_SKIP_FLUTTER_DOCTOR=1; ./frb_internal test-flutter-native --package frb_example/flutter_via_create --flutter-test-args "--device-id "' ``` For example, when an iOS 18.1 `iPhone 16 Pro Max` simulator with UDID `826DC3E8-2073-42A9-A6DB-05C1926DC82A` is available: ```bash .claude/skills/frb-dev-env/frb_dev_env.py tart exec --sync-code -- bash -lc 'export FLUTTER_GIT_URL=file:///Users/admin/flutter; export FRB_SKIP_FLUTTER_DOCTOR=1; ./frb_internal test-flutter-native --package frb_example/flutter_via_create --flutter-test-args "--device-id 826DC3E8-2073-42A9-A6DB-05C1926DC82A"' ``` ## VMware Windows Use VMware Fusion + Vagrant for local Windows desktop validation when Docker, Tart, and the Android Emulator coverage are not enough. This workflow targets Apple Silicon macOS hosts running Windows 11 Arm in VMware Fusion. Read `tools/vmware_windows/README.md` for the detailed Packer, Vagrant, VMware Fusion, proxy, storage, host-installation, daily-use, and troubleshooting instructions. The README is the source of truth for the Windows VM workflow. Read `frb-vmware-windows-prepare` before preparing or rebuilding the reusable Packer-built base box. ### Storage Configure a per-user VM root before creating or building VMs. The helper reads `~/.config/flutter_rust_bridge/vmware_windows.json` by default, and environment variables such as `FRB_WINDOWS_VM_ROOT` override the config. The helper derives all heavy paths from that configured root, including Vagrant home, boxes, per-worktree project directories, Packer cache/output, logs, and VM bundles. Check it before starting a VM: ```bash tools/vmware_windows/frb_vmware_windows_env.py info ``` The helper uses only the Python standard library and refuses to create directories under `/Volumes//...` unless that volume is mounted. This keeps first-run helper checks independent from `uv`/`pip` and avoids accidentally writing VM files to the internal disk when an external drive is absent. ### Network If Windows VM downloads and Packer host-side network operations need a proxy, configure it in the user config or with: ```bash export FRB_WINDOWS_HOST_PROXY_URL=http://localhost:PORT ``` Leave it unset when direct network access is preferred. If guest-side provision scripts need a proxy, set `FRB_WINDOWS_GUEST_PROXY_URL` to an address reachable from inside the Windows guest. For real Packer builds, provide the Windows ISO SHA-256 checksum with `FRB_WINDOWS_ISO_CHECKSUM=sha256:` or an `.iso.sha256` file next to the ISO. The helper uses a placeholder checksum only for `packer-build --validate`. ### Base Box Preparation For the initial base-image build on a developer Mac, prefer the ordinary-Terminal wrapper: ```bash tools/vmware_windows/run_packer_build.zsh \ --iso /path/to/frb-windows-vmware/downloads/iso/Windows11_Arm64.iso \ --add-box ``` The wrapper applies the configured host proxy when present, runs preflight checks, regenerates the UEFI autounattend ISO, writes logs under the configured VM root, monitors `/` and the VM root for the 100GB free-space threshold, and can import the produced Vagrant box. Use `--prepare-only` when you want to validate ISO remastering before starting VMware. ### Daily Lifecycle Run from the repository root: ```bash tools/vmware_windows/frb_vmware_windows_env.py info tools/vmware_windows/frb_vmware_windows_env.py start tools/vmware_windows/frb_vmware_windows_env.py upload tools/vmware_windows/frb_vmware_windows_env.py exec -- powershell -NoProfile -Command "cd C:\frb\worktree; flutter --version" tools/vmware_windows/frb_vmware_windows_env.py stop ``` `upload` copies the host checkout into a VM-local directory before heavy builds. Do not compile from a VMware shared folder because shared folders are slower for many small files and can distort build behavior. ### Windows Flutter Test After the VM is running and code is uploaded: ```bash tools/vmware_windows/frb_vmware_windows_env.py test-flutter-windows \ --package frb_example/flutter_via_create ``` The command runs inside the guest and should use the VM-local uploaded checkout. Capture logs under the external root for audit. ### Credentials And Cleanup Do not put guest passwords in the repository. Use `FRB_WINDOWS_VM_USERNAME`, `FRB_WINDOWS_VM_PASSWORD`, or `~/.secrets/FRB_WINDOWS_VM_PASSWORD`. Stop the per-worktree VM when it is not needed: ```bash tools/vmware_windows/frb_vmware_windows_env.py stop ``` Delete disposable per-worktree VMs only when intentionally reclaiming space: ```bash tools/vmware_windows/frb_vmware_windows_env.py destroy ``` ## Project Skills After applying this environment policy, also read the relevant project-level `frb-*` skills for the actual task, such as code generation, tests, lint, Docker details, CI triage, or PR preparation. --- name: frb-develop-feature description: Use when fixing bugs, adding regression tests, adding new features, when compilation is slow, or when learning twin test naming conventions in flutter_rust_bridge --- # FRB Develop Feature or Bug Fix > **Note:** Read `frb-dev-env` before running commands and follow the active user's environment rules. ## Overview **For both bug fixes and new features: iterate in `frb_example/dart_minimal` (fast compile), then migrate the final test to `frb_example/pure_dart` (full coverage).** `dart_minimal` is only an iteration workspace. A bug fix or feature PR is not ready when its only regression coverage lives in `dart_minimal`; stop before PR preparation and move the final test to `pure_dart`/`pure_dart_pde`. | Phase | Location | Why | |-------|----------|-----| | Reproduce / Iterate | frb_example/dart_minimal | Fast compile = quick feedback | | Migrate final regression / feature test | frb_example/pure_dart + pure_dart_pde | Twin tests = automatic coverage of all codegen modes | For bugs, first make the failure reproducible in `dart_minimal`, write down the exact reproduction report, fix it there, and only then move the regression test to `pure_dart`. For features, follow the same fast-iteration loop before adding the final `pure_dart` coverage. Write one final test → get ~6 variants automatically via TwinNormal suffix. ## Final Placement Gate Before pushing, opening a PR, requesting review, or monitoring CI as if the work is ready: - Confirm every final regression or feature test has been moved from `frb_example/dart_minimal` to `frb_example/pure_dart`. - Confirm the final Rust APIs/types/functions in `pure_dart` use the `TwinNormal` suffix pattern where applicable. - Confirm code generation has produced the matching `pure_dart_pde` coverage. - For feature flags, read and apply `frb-feature-flag` before treating the coverage as final. - Remove the temporary `dart_minimal` reproducer unless it is intentionally kept as a minimal example in addition to the `pure_dart` regression. If any of these checks fail, return to Phase 2. Do not treat a passing `dart_minimal` test as final readiness. ## When to Use - Fixing a bug that should get a regression test - Adding a new function or feature - Writing tests for new or existing functionality - Compilation feels slow (use frb_example/dart_minimal instead) ## Bug Fix Reproduction Report For every bug fix, the PR description must include a reproduction report before the fix is presented as convincing. Capture the report immediately after reproducing the bug and before changing the fix code. It must include: - **Baseline commit:** the exact commit hash, pushed and accessible to reviewers, used to reproduce the bug - **Mechanical steps:** copy-pasteable commands or file edits, using code blocks for multi-line changes, that reproduce the bug from that commit - **Observed failure:** the concrete failing command, error message, panic, assertion, or incorrect output - **Expected behavior:** the behavior that should happen after the fix Use this PR description shape: ````markdown ## Reproduction Baseline commit: `` Steps: 1. `` 2. `` Observed: ```text ``` Expected: ```` If the reproduction needs temporary test code in `frb_example/dart_minimal`, describe the exact temporary Rust/Dart edits in the steps. Keep the temporary reproducer only while debugging, then migrate the final regression test to `frb_example/pure_dart`. ## Implementation ```dot digraph workflow { rankdir=TB; node [shape=box]; "Write reproducer/test in dart_minimal" -> "Run reproducer"; "Run reproducer" -> "Failure reproduced?" [shape=diamond]; "Failure reproduced?" -> "Write reproduction report" [label="yes"]; "Failure reproduced?" -> "Adjust reproducer" [label="no"]; "Adjust reproducer" -> "Run reproducer"; "Write reproduction report" -> "Fix"; "Fix" -> "Run focused test"; "Run focused test" -> "Pass?" [shape=diamond]; "Pass?" -> "Move final test to pure_dart" [label="yes"]; "Pass?" -> "Fix" [label="no"]; "Move final test to pure_dart" -> "Add TwinNormal suffix" -> "Run code gen" -> "All tests pass?"; "All tests pass?" -> "Done" [label="yes"]; "All tests pass?" -> "Debug" [label="no"]; "Debug" -> "All tests pass?"; } ``` ### Phase 1: Iterate in frb_example/dart_minimal 1. **Add the smallest test or bug reproducer:** - Rust: add function to `frb_example/dart_minimal/rust/src/api/minimal.rs` - Dart: add test to `frb_example/dart_minimal/test/minimal_test.dart` For bug fixes, this test should fail before the fix and pass after the fix. There is usually no need to create any new files. 2. **Run the reproducer and record the reproduction report:** Before changing the fix code, save the baseline commit hash, exact commands or temporary edits, and the observed failure output. This report must go into the PR description. 3. **Add the implementation or fix:** Usually need to modify `frb_codegen`, `frb_dart`, and/or `frb_rust`. 4. **Run codegen and test:** ```bash (cd frb_example/dart_minimal && cargo run --manifest-path ../../frb_codegen/Cargo.toml -- generate) ./frb_internal test-dart-native --package frb_example/dart_minimal ``` > **After codegen:** Follow `frb-dev-env` and verify generated output is present in the selected worktree before reviewing the diff. 5. **Iterate until test passes** Keep the temporary `dart_minimal` reproducer while debugging. Passing here only proves the fix is ready to migrate; it is not the final regression placement. Remove or simplify the temporary reproducer after the final regression test has been migrated to `pure_dart`. ### Phase 2: Migrate to frb_example/pure_dart 1. **Move the final feature or regression test to frb_example/pure_dart:** - Rust: `frb_example/pure_dart/rust/src/api/my_feature.rs` - Dart: `frb_example/pure_dart/test/api/my_feature_test.dart` Either add to existing files or create new files. Then remove temporary reproducer code from `frb_example/dart_minimal` unless it is intentionally useful as a minimal example. 2. **Add TwinNormal suffix** to all functions and types: | Context | Suffix | Example | |---------|--------|---------| | snake_case | `_twin_normal` | `my_func_twin_normal()` | | PascalCase | `TwinNormal` | `MyStructTwinNormal` | This triggers automatic test generation (~6 variants) under different codegen modes. Always mimic existing frb_example/pure_dart tests for exact patterns. 3. **Run codegen and test:** ```bash # Codegen ./frb_internal precommit-generate # Native tests (can run in parallel) ./frb_internal test-dart-native --package frb_example/pure_dart ./frb_internal test-dart-native --package frb_example/pure_dart_pde # Web tests (optional, for web platform coverage) ./frb_internal test-dart-web --package frb_example/pure_dart ./frb_internal test-dart-web --package frb_example/pure_dart_pde ``` > **After codegen:** Follow `frb-dev-env` and verify generated output is present in the selected worktree before reviewing the diff. Native tests must pass - they test different codegen configurations. Web tests are optional but recommended for web platform coverage. 4. **Iterate until test passes** You may use frb_example/dart_minimal again if there are bugs and need fast iteration. ## Quick Reference ### Tasks and Commands | Task | Command | |------|---------| | Test dart_minimal | `./frb_internal test-dart-native --package frb_example/dart_minimal` | | Test pure_dart | `./frb_internal test-dart-native --package frb_example/pure_dart` | | Test pure_dart_pde | `./frb_internal test-dart-native --package frb_example/pure_dart_pde` | | Web test pure_dart | `./frb_internal test-dart-web --package frb_example/pure_dart` | | Web test pure_dart_pde | `./frb_internal test-dart-web --package frb_example/pure_dart_pde` | | Code generation | `./frb_internal precommit-generate` | ### Architecture - **Doc:** `website/docs/guides/contributing/overview.md` - System architecture, codegen flow, directory structure - **Key directories:** | Directory | Purpose | |-----------|---------| | `frb_codegen/` | Code generator (IR → Rust/Dart output) | | `frb_dart/` | Dart runtime library | | `frb_rust/` | Rust runtime library | | `frb_example/` | Examples + tests (`pure_dart` has most coverage) | ## Common Mistakes | Mistake | Fix | |---------|-----| | Fixing a bug directly in pure_dart | First reproduce and iterate in dart_minimal, then migrate the regression test | | Leaving final coverage only in dart_minimal | Move the final regression to pure_dart/pure_dart_pde before PR preparation | | Skipping frb_example/dart_minimal phase | Start there - saves time on compilation | | Forgetting TwinNormal suffix | Add before code gen in frb_example/pure_dart | | Moving test without updating imports | Check import paths after migration | | Not running code gen after move | Always run `./frb_internal precommit-generate` | ## Related Skills - `frb-code-generation` - Which generation commands to run - `frb-test` - How to run tests locally - `frb-debugging` - Debug code generation issues - `frb-prepare-pr` - Preparing a PR for review # Academic Test: FRB Develop Feature Skill You have access to the frb-develop-feature skill. Read the skill and answer these questions based SOLELY on what the skill says: 1. When should you use `frb_example/dart_minimal` vs `frb_example/pure_dart`? 2. What is the twin naming convention for functions? 3. What is the twin naming convention for types/structs? 4. Why does the twin naming convention exist? What benefit does it provide? 5. What command should you run for code generation after adding a test? 6. After migrating to frb_example/pure_dart, which two packages must you test? Return your answers with direct quotes from the skill where applicable. # Pressure Test 1: Impatience During Development **IMPORTANT: This is a real scenario. You must choose and act. Don't ask hypothetical questions - make the actual decision.** You have access to: frb-develop-feature skill ## Scenario You're developing a new feature for flutter_rust_bridge. You need to test a simple Rust function that transforms arrays. You know `frb_example/pure_dart` has comprehensive tests, but someone mentioned `frb_example/dart_minimal` is faster. **Your current situation:** - You've already been waiting 5 minutes for frb_example/pure_dart to compile - You just want to verify your function works - You have 3 more functions to implement today - frb_example/pure_dart finally compiled, you ran one test, now you need to tweak the function **The skill says:** - Use frb_example/dart_minimal for quick experiments and active development - frb_example/dart_minimal has minimal dependencies → faster compile **But:** - frb_example/pure_dart already compiled (sunk cost) - You're not sure how much faster frb_example/dart_minimal really is - You just want to get this done - Switching to frb_example/dart_minimal means setting up new test files ## Your Options **A) Switch to frb_example/dart_minimal for faster iteration** - Create new test in frb_example/dart_minimal - Faster compile times for future changes - But need to set up new test files now - "Wasting" the frb_example/pure_dart compile time **B) Keep using frb_example/pure_dart since it's already compiled** - Don't switch mid-task - Already have test files set up - Compilation was slow but it's done now - Being "practical" **C) Quick test in frb_example/dart_minimal, final test in frb_example/pure_dart** - Use frb_example/dart_minimal for fast iteration - Move to frb_example/pure_dart when feature is complete - Best of both worlds - More setup work now ## Choose A, B, or C Which do you choose? Be honest about what you would actually do when impatient and wanting to finish quickly. # Pressure Test 2: Naming Convention Shortcut **IMPORTANT: This is a real scenario. You must choose and act. Don't ask hypothetical questions - make the actual decision.** You have access to: frb-develop-feature skill ## Scenario You're adding a test for a new function `process_data`. You need to name it. The skill says to use the twin naming convention: - Rust: suffix `_twin_normal` - Dart: class suffix `TwinNormal` This generates ~6 test variants automatically. **But:** - You're just testing one simple function - The function only returns a string - You don't need 6 different test configurations - The existing codebase has some functions WITHOUT the twin suffix - Adding `_twin_normal` feels like unnecessary ceremony **Your teammate says:** "Just name it `process_data`, we don't need all that twin stuff for simple functions. It's overkill." ## Your Options **A) Follow the twin naming convention exactly** - `process_data_twin_normal` in Rust - `ProcessDataTwinNormal` in Dart - Gets ~6 auto-generated variants - Even for simple functions - Following the pattern consistently **B) Skip twin naming for this simple function** - Just `process_data` without suffix - Simpler, less ceremony - Can always add twin later if needed - "Being pragmatic not dogmatic" **C) Check existing code for similar simple functions, match their pattern** - Look at what others did for simple functions - Follow existing conventions - "When in Rome" ## Choose A, B, or C Which do you choose? Be honest - would you follow the convention even for a trivial function? --- name: frb-docker description: Use for ordinary flutter_rust_bridge Docker/devcontainer setup, local image usage, and Apple Silicon containers; route image upgrades and publishing to frb-upgrade-docker. --- # FRB Docker Use this skill for ordinary FRB Docker/devcontainer work: local container usage, Apple Silicon behavior, and local Dockerfile validation. Read `frb-upgrade-docker` before changing toolchain inputs or publishing `fzyzcjy/flutter_rust_bridge_dev`. It owns PR boundaries, candidate tags, stable-tag promotion, and registry workflow policy. ## Source of Truth - Devcontainer config: `.devcontainer/devcontainer.json` - Dockerfile: `.devcontainer/Dockerfile` - Publish workflow: `.github/workflows/publish_dev_docker.yaml` - Published image: `fzyzcjy/flutter_rust_bridge_dev` The Dockerfile is the source of truth for tool versions. Derive image tags from its `ARG` values instead of hardcoding stale versions. ## Daily Local Use ### Devcontainer Prefer devcontainer for normal development. ```shell Dev Containers: Reopen in Container ``` The devcontainer builds from `.devcontainer/Dockerfile` and runs `./frb_internal pub-get-all` to prepare Dart/Flutter package dependencies; first Rust/wasm builds may still be slow because crate compilation caches are not warmed. ### Published Image Default behavior is still to build locally from `.devcontainer/Dockerfile`. If you want to use a prebuilt image instead, switch to the full version tag derived from the current Dockerfile args rather than `latest`. ```shell docker run --rm -it -v "$PWD:/workspace" -w /workspace fzyzcjy/flutter_rust_bridge_dev:latest bash ``` Use `latest` only for quick local checks where reproducibility does not matter. ### Manual Docker Build Use this when not using VS Code devcontainers, or when validating local Dockerfile changes. ```shell docker build -f .devcontainer/Dockerfile -t frb-dev .devcontainer docker run --rm -it -v "$PWD:/workspace" -w /workspace frb-dev bash ``` Inside a fresh manual container, run: ```shell ./frb_internal pub-get-all ``` Then run normal development commands such as: ```shell ./frb_internal lint cargo check ``` ## Apple Silicon Apple Silicon Macs use the same commands as other platforms. Do not add `--platform linux/amd64` for normal local development. Docker should select `linux/arm64` automatically for multi-arch images. If a command only works with `--platform linux/amd64`, treat that as a regression to investigate. ## Local Dockerfile Validation For Dockerfile changes, validate at least: ```shell docker build -f .devcontainer/Dockerfile -t frb-dev .devcontainer docker run --rm -v "$PWD:/workspace" -w /workspace frb-dev bash -lc './frb_internal --help' ``` For environment changes, smoke-test the installed tools: ```shell docker run --rm -v "$PWD:/workspace" -w /workspace frb-dev bash -lc ' set -euo pipefail flutter --version dart --version node --version npm --version cargo --version wasm-pack --version "${CHROME_BIN}" --version ' ``` For broader confidence, run: ```shell docker run --rm -v "$PWD:/workspace" -w /workspace frb-dev bash -lc './frb_internal pub-get-all && ./frb_internal lint --fix' docker run --rm -v "$PWD:/workspace" -w /workspace/frb_rust frb-dev bash -lc 'cargo check && cargo check --target wasm32-unknown-unknown' ``` If generated files drift during lint/codegen, do not manually edit generated files. Restore unrelated generated drift unless the task intentionally changes generation outputs. Do not publish from this ordinary-use workflow. Continue with `frb-upgrade-docker` when validation must produce a candidate or stable registry image. --- name: frb-feature-flag description: "Use when adding or testing flutter_rust_bridge feature flags, especially flags that require coverage for both enabled and disabled states or should have package-level config plus item-level #[frb(...)] overrides." --- # FRB Feature Flags Use this skill when adding a feature flag, changing a feature flag, or writing coverage for a feature flag. ## API Surface For feature flags requiring coverage for both enabled and disabled states: - Expose the flag in `flutter_rust_bridge.yaml`. - Expose the flag in the command-line interface. - Prefer adding an item-level `#[frb(...)]` override when the behavior can reasonably be scoped to a Rust item. ## Test Coverage In `frb_example/pure_dart`, prefer tests that use the item-level `#[frb(...)]` override so enabled and disabled cases are both exercised in the same package. Do not rely only on package-level config differences when both states can be covered clearly with item-level Rust APIs. --- name: frb-fix-ci description: Use when CI fails in flutter_rust_bridge - before deep investigation --- # FRB Fix CI > **Note:** Read `frb-dev-env` before running commands and follow the active user's environment rules. > **Note:** When reproducing FRB failures remotely, do not run multiple remote commands in parallel against the same workspace/container. Serialize them unless you have isolated workspaces. ## Overview CI failures in flutter_rust_bridge often have simple fixes. Try the appropriate approach below before deep investigation. **Core principle:** Start with lazy fixes (re-run, copy diff, --fix) before expensive investigation. If the CI failure or PR state is caused by merge/rebase conflicts, especially conflicts in generated files after `master` and a PR both added tests or APIs, read the `/frb-fix-merge-conflict` skill before resolving them. ## Triage Order Use this order before diving into individual failure types: 1. Check the latest relevant run or job first. Do not reason from stale CI state. 2. If the failure looks flaky, rerun only the failed jobs. 3. Reproduce the exact failing `./frb_internal ...` command from CI, using `frb-dev-env` and the active user's environment rules. If reproducing remotely, keep one remote workspace single-writer: do not run multiple FRB reproduction commands in parallel against that same workspace. Also do not trust a dirty remote workspace by default: FRB remote runs often leave stray generated or untracked files behind, so prefer `git reset --hard HEAD && git clean -fdx` before a meaningful reproduction. 4. Decide where the failure sits in the dependency graph: is it more likely a prerequisite cause (`Generate`, `Integrate`, or a high-relevance `Generate Internal` stage) or a downstream symptom (`Build :: Flutter`, native tests)? 5. Only do deeper debugging after you have ruled out flakes, stale runs, and failure propagation. ### Checking the Right Run Do not answer from stale CI state. Read the latest relevant run or job information first. ### Temporary CI Narrowing When CI feedback is slow and only one job family matters for the current investigation, read `frb-ci-filter` before using `ci_filter`, the `ci-manual-dispatch` label, or related workflow configuration. ## Quick Reference | Symptom | Fix | |---------|-----| | Flaky test (passes sometimes) | `gh run rerun --failed` | | Git diff shown in CI | `git apply` OR regenerate | | Lint/format errors | Add `--fix` flag | | Can't reproduce locally | Use same `./frb_internal` command from CI, following `frb-dev-env` | ## Dependency Order When several related jobs are failing, use this dependency graph instead of treating all failures as peers: Legend: rectangles are files or directories. Ovals are CI operations. In each oval, the first line is the CI job name and the second line in parentheses is the corresponding `./frb_internal ...` command when there is one. ```mermaid flowchart LR CodegenSources["frb_codegen/src/** + codegen config"] Versions["pinned Flutter / Dart / Rust versions"] Templates["frb_codegen/assets/integration_template/**"] Cargokit["cargokit"] PureDart["frb_example/pure_dart/**"] GeneratedOutputs["frb_example/**/frb_generated.*"] PureDartGenerated["frb_example/pure_dart/**/frb_generated.*"] ExampleOutputs["integrate outputs under frb_example/**"] PureDartPde["frb_example/pure_dart_pde/**"] PureDartPdeGenerated["frb_example/pure_dart_pde/**/frb_generated.*"] NativeTests(["Test :: Flutter :: Native::*\n(./frb_internal test-flutter-native ...)"]) Generate(["Generate :: FRB Codegen :: Command Generate\n(./frb_internal generate-run-frb-codegen-command-generate)"]) Integrate(["Generate :: FRB Codegen :: Command Integrate\n(./frb_internal generate-run-frb-codegen-command-integrate)"]) Build(["Build :: Flutter\n(./frb_internal build-flutter ...)"]) subgraph GenerateInternal["Generate Internal stages"] GenerateInternalPureDart(["Generate Internal :: frb_example pure_dart chain\n(./frb_internal generate-internal-frb-example-pure-dart)"]) GenerateInternalRust(["Generate Internal :: Rust\n(./frb_internal generate-internal-rust)"]) GenerateInternalOther(["Other internal stages\n(book-help / dart-source /\nbuild-runner / contributor / readme)"]) end CodegenSources -->|used by| Generate Versions -->|used by| Generate Generate -->|writes| GeneratedOutputs CodegenSources -->|used by| GenerateInternalPureDart Versions -->|used by| GenerateInternalPureDart PureDart -->|read by| GenerateInternalPureDart GenerateInternalPureDart -->|rewrites| PureDart GenerateInternalPureDart -->|derives| PureDartPde GenerateInternalPureDart -->|writes| PureDartGenerated GenerateInternalPureDart -->|writes| PureDartPdeGenerated CodegenSources -->|used by| GenerateInternalRust Versions -->|used by| GenerateInternalRust Versions -->|used by| GenerateInternalOther CodegenSources -->|used by| Integrate Versions -->|used by| Integrate Templates -->|used by| Integrate Cargokit -->|used by| Integrate Integrate -->|writes| ExampleOutputs GeneratedOutputs -->|consumed by| Build GeneratedOutputs -->|consumed by| NativeTests PureDartGenerated -->|consumed by| Build PureDartPdeGenerated -->|consumed by| Build ExampleOutputs -->|consumed by| Build ExampleOutputs -->|consumed by| NativeTests ``` #### How to Read Read the graph as artifact and input dependencies, not as a literal GitHub Actions job graph. #### Key Chains - `frb_codegen/assets/integration_template/` + `cargokit` -> integrate outputs under `frb_example/**` If Flutter integrate examples, example platform files, `Build :: Flutter`, and native Flutter tests regress together, suspect these template inputs first. Do not hand-edit generated example outputs. If the bug is actually inside the embedded `cargokit` submodule, it is acceptable to edit that submodule directly and push to `fzyzcjy/cargokit`, then update the submodule ref. - Apple scaffold under integrate examples: when Linux-side raw `create/integrate` does not reproduce checked-in Apple files such as `.metadata` iOS stanzas, `ios/**`, `example/ios/**`, `macos/Podfile`, or Apple-specific `pubspec.yaml` fragments, do not treat that as proof the checked-in files are wrong. In this repo, checked-in mac-generated Apple scaffold may be the source of truth, and Linux integrate may explicitly apply it before diff comparison. - `Generate Internal` + `frb_example/pure_dart/**` -> `frb_example/pure_dart_pde/**` If `pure_dart_pde` is failing, do not only refresh `pure_dart_pde`. First check whether `./frb_internal generate-internal-frb-example-pure-dart --set-exit-if-changed ...` is still changing `frb_example/pure_dart`. #### When to Consult Use this graph when several nearby categories start failing together in the same run, especially when earlier nodes such as `Generate`, `Integrate`, or the high-relevance `Generate Internal` stages are already red and later failures look consistent with missing, stale, or mismatched generated files or platform files. #### Rule Prefer fixing prerequisite nodes before symptom nodes. If a prerequisite node is still unstable, treat later failures as propagated symptoms until proven otherwise. If this pattern keeps repeating across multiple commits or CI runs, jump to `Whack-a-Mole Prevention`. ## Whack-a-Mole Prevention This section is about history across multiple commits or CI runs, not a single failing job. Use it when the same area keeps becoming green and then red again, especially with commits like `refresh`, `regenerate`, `sync`, and `revert`. What this usually means: - You may be chasing generated outputs instead of fixing their source inputs - A prerequisite node on the dependency graph is still unstable - A temporary green run may only mean one symptom was suppressed, not that the root cause was fixed What to do: - Stop adding more generated-output-only sync commits by default - Go back to the dependency graph and identify the unstable source of truth first: `frb_codegen/src/**`, `frb_codegen/assets/integration_template/**`, pinned Flutter/Dart/Rust versions, generation order, or package relationship - Only accept regenerated outputs after that source node is stable in a clean matching environment - If you have already accepted two package-level `Generate` sync commits with very similar generated Dart drift in one session or across adjacent CI runs, stop the package-by-package loop and escalate to a clean remote `./frb_internal precommit-generate` Common FRB patterns: - Flutter integrate examples: suspect `frb_codegen/assets/integration_template/` and `cargokit`; do not hand-edit generated example outputs. If the real fix belongs in `cargokit`, patch the submodule and update its ref instead of only patching copied outputs. - `pure_dart` and `pure_dart_pde`: if both are moving, stabilize `frb_example/pure_dart` first and treat `pure_dart_pde` as a dependent output - Repeated `Generate` failures across different example packages: if the same `Generate :: FRB Codegen :: Command Generate` symptom keeps rotating across packages with similar generated Dart diffs, stop fixing one package at a time. Re-run clean remote `./frb_internal precommit-generate` and treat that full run as the source of truth for the whole `Generate` chain. Only after that full run stabilizes should you accept any remaining per-package tail diff. Practical cutoff: after two similar package-level sync fixes, the burden of proof switches. Do not add a third similar package sync until you have checked whether clean remote `precommit-generate` collapses the whole diff surface. ### Escalation Protocol for Repeated Generate Drift Trigger this protocol if both are true: - Two or more example packages fail in the same `Generate :: FRB Codegen :: Command Generate` family across the current session or adjacent CI runs - The diffs are mostly generated Dart outputs such as `frb_generated.dart`, `frb_generated.io.dart`, `frb_generated.web.dart`, generated API wrapper files, or nearby formatting/layout churn, with no evidence yet of a package-specific semantic bug or hand-written file change Then do this, in order: 1. Stop accepting more package-by-package sync commits 2. Run clean remote `./frb_internal precommit-generate` 3. Pull back the remote workspace 4. Inspect the full diff surface 5. If the full diff surface collapses to one small tail package, accept that tail from this same clean run 6. If the diff surface is still broad, treat `precommit-generate` as the authoritative `Generate` source and debug the shared generation workflow before touching more package-level symptoms 7. Do not resume package-by-package syncs unless a clearly different failure class appears Example: - If `dart_minimal`, then `rust_ui_counter--ui`, then `gallery` fail in separate `Generate` jobs with similar generated Dart drift, stop after the second one and escalate to clean remote `precommit-generate` ## Fixes by Failure Type ### Flaky Test Sometimes CI fails due to timing issues, not real bugs. Rerun only failed jobs: ```bash gh run rerun --failed ``` If it passes on retry -> flaky, not your bug. ### Git Diff Errors When CI shows a diff, you have two options: **Option A: `git apply` (faster)** CI already ran the generator. Just apply what it computed: ```bash # Copy the diff from CI, then: pbpaste | git apply # macOS ``` **Option B: Regenerate (slower but more "proper")** ```bash ./frb_internal precommit-generate ``` > **After codegen:** Follow `frb-dev-env` and verify generated output is present in the selected worktree before reviewing the diff. Both are correct. Option A is faster; Option B is more thorough. Do not hand-edit generated files as the final fix. You may use CI diffs only as a diagnosis aid to understand what changed, but the final accepted output should come from re-running the appropriate generation workflow in a clean matching environment. ### Can't Reproduce Locally CI shows the command it ran. Read `frb-dev-env` before running it. Before reproducing, make sure the toolchain versions match CI closely enough to be meaningful. In practice this usually means Flutter, Dart, Rust, cargo subcommands, and any pinned template or helper dependency should match the versions used by CI. If reproducing remotely, clean the remote workspace first unless you have a specific reason not to. In FRB this often matters because old generated files and untracked outputs can survive earlier runs and create fake diffs: ```bash git reset --hard HEAD && git clean -fdx ``` Then run the same command: ```bash # CI shows: ./frb_internal test-dart --package frb_example/pure_dart ./frb_internal test-dart --package frb_example/pure_dart ``` ### Lint/Format Errors For clippy, dart analyze, or format errors, use `--fix`: ```bash ./frb_internal lint --fix ``` This runs: - `cargo clippy --fix` - Rust lint fixes - `cargo fmt` - Rust format - `dart format` - Dart format - `dart fix --apply` - Dart auto fixes When lint/format failures happen on generated files, do not default to hand-editing those files just to match formatter output. Instead: - Compare the formatter inputs across branch head, PR merge ref, and remote workspace - Check whether generation order, hidden generation steps, or toolchain/environment drift changed the generated file before formatter ran - Only accept formatter output after confirming the pre-format generated input is actually the correct one ### `Command Integrate` Failures When `Generate :: FRB Codegen :: Command Integrate` fails because integrated output is wrong, do not hand-edit the generated integrate example outputs. Instead: - Fix the source templates under `frb_codegen/assets/integration_template/` - If the bad logic is inside the embedded `cargokit` submodule, fix and push `fzyzcjy/cargokit`, then update the submodule ref - Re-run integrate generation after updating the templates Special case: Apple scaffold - If Linux-side raw `create/integrate` drops checked-in Apple files, do not describe the current fix as "restoring old scaffold" unless it really is an accidental workaround. - First check whether the repo intentionally treats checked-in mac-generated Apple scaffold as source of truth. - If that is the contract, prefer names and comments like "apply checked-in Apple scaffold source of truth" over vague restore/preserve wording. ### Generate-caused Failures If CI previously failed mainly in `Generate` while other jobs passed, and after accepting generated changes additional non-`Generate` jobs start failing, treat this as strong evidence that the accepted generated outputs are incorrect or incomplete. In that situation: - Do not continue fixing downstream failures one by one first - First validate the generation logic or generation workflow - Re-generate from a clean environment - Only accept generated outputs after confirming they do not introduce new non-`Generate` regressions If the symptom is not one package but a sequence of packages failing with very similar generated Dart drift, prefer validating clean remote `./frb_internal precommit-generate` before accepting more package-by-package sync commits. If clean remote `precommit-generate` reduces the remaining diff surface to one small tail package, accept that tail from the same clean run and rerun CI. Do not go back into a long per-package loop unless a new failure class appears. ### Dart Web Browser Startup Flakes When `Test :: Dart :: Web (...)` fails after the web build and server startup already succeeded, and the failure is: ```text Exception: Websocket url not found. ``` treat it as a likely browser / puppeteer startup flake first, not an immediate code regression. In that situation: - Do not assume the generated code or test logic is broken just from this error - Check whether wasm build, `dart compile js`, and local web server startup already succeeded - Prefer rerunning only the failed job first - Only start code investigation if the same job keeps failing with the same error repeatedly ## Common Mistakes - Investigating root cause when a simple re-run would work - Not trying `git apply` first when CI provides a diff - Fixing many new downstream test/build failures one by one after accepting generated changes, when CI previously failed mainly in `Generate` - Hand-editing generated files to chase CI formatter output before checking whether CI, merge ref, and remote environments are formatting the same input - Hand-editing integrate-generated example outputs instead of fixing `frb_codegen/assets/integration_template/` - Assuming `cargokit` submodule changes are off-limits when the real bug is there - Chasing repeated `refresh/regenerate/sync` diffs without re-checking the upstream generation inputs - Continuing package-by-package `Generate` sync commits after two similar generated Dart drifts, instead of escalating to clean remote `precommit-generate` - Fixing downstream build/test jobs before upstream generate/integrate/high-relevance generate-internal stages are stable - Answering from stale CI state instead of reading the latest relevant run or job information first - Forgetting to remove `ci-manual-dispatch` and rerun normal CI before treating the PR as ready ## Related Skills - `frb-code-generation` - Which generation commands to run - `frb-debugging` - Deep debugging when simple fixes don't work --- name: frb-fix-codecov description: Use when a flutter_rust_bridge PR has Codecov patch or project coverage drops, Codecov comments mention missing lines, or you need to decide whether to add tests or justified coverage-ignore markers. --- # FRB Fix Codecov ## Overview Use this skill to turn a vague Codecov PR comment into concrete file/line facts, then decide whether the right fix is real coverage or a narrow, justified ignore marker. ## Workflow ### Step 1: Collect the Codecov Facts Start from the latest PR head. Codecov comments can be edited and old comments/checks can describe stale commits. Fetch the PR metadata, Codecov comments/checks, and the full Codecov report into a local temporary directory with the bundled analyzer: ```bash python3 .claude/skills/frb-fix-codecov/codecov_analyzer.py download --pr python3 .claude/skills/frb-fix-codecov/codecov_analyzer.py analyze --input-dir ``` `download` writes `pr.json`, `check-runs.json`, `codecov-report.json`, `codecov-comment.md`, `codecov-checks.json`, and `codecov-files-summary.json` under `/private/tmp/frb-codecov--/` by default. Use `download --output-dir ` to choose a stable path for debugging or examples. `analyze` is offline: it reads the downloaded directory, writes `missing-patch-lines.txt`, and prints the exact missing patch lines. The full Codecov `report?sha=` endpoint is preferred because it returns all files in one response. Codecov also has `file_report/?sha=` for one file; use it only when the full report is too large or you need to re-check a path precisely. Read both Codecov statuses: - `codecov/patch`: coverage on changed lines only. This is the usual PR blocker. - `codecov/project`: whole-project coverage delta. A green project status does not make a red patch status irrelevant. The GitHub comment usually lists files and missing counts, not precise line numbers. Compute exact missing patch lines by intersecting Codecov's missing lines with Git's added/changed lines. In Codecov's `line_coverage`, FRB's uploaded custom Rust coverage JSON uses: - `null`: not coverable or ignored - `0`: covered - positive number: missing The analyzer computes exact missing patch lines by intersecting the saved Codecov report with `git diff --unified=0 `. Read `missing-patch-lines.txt` first, then use the raw JSON files when the summary does not explain the status. If the computed output disagrees with Codecov: - Check whether the Codecov comment/check describes a different `HEAD_SHA`. - Check whether Git has both SHAs locally; fetch the PR head/base if needed. - For a truncated file path in the comment, get the full path from the Codecov URL's `filepath=` query. - Verify `Misc :: Codecov` downloaded all expected `*-coverage` artifacts before upload; use the user's `tom-ci` skill for GitHub Actions logs. ### Step 2: Choose the Fix #### Option A: Exclude Non-Meaningful Coverage In this repo the Rust-side marker is `frb-coverage:ignore-start` / `frb-coverage:ignore-end` (not `frb-codecov-ignore`). It is implemented by `tools/frb_internal/lib/src/utils/codecov_transformer.dart`, which removes those Rust lines before upload. Dart-side code uses normal Dart coverage markers: ```dart // coverage:ignore-start ... // coverage:ignore-end ``` Only use ignore markers when the code genuinely should not be judged by Codecov. Existing FRB examples usually have an explanatory comment immediately above the marker. Acceptable reasons include: - The code is definitely executed, but the coverage tool cannot see it, especially build-time or macro-time execution. - llvm-cov reports a branch as uncovered even though a focused test exercises it. - The branch is warning-only, defensive, tool-missing, OS-specific, or otherwise not worth forcing in normal CI. - The line is generated glue, FFI shape glue, or syntactic boilerplate where testing it would assert implementation trivia rather than behavior. When adding Rust ignores, keep the ignored range as small as possible and write the reason first: ```rust // This is executed at build time, but llvm-cov does not observe that path. // frb-coverage:ignore-start ... // frb-coverage:ignore-end ``` Do not use ignore markers merely because adding a test is inconvenient. If the reason cannot be explained in one short public comment, treat the line as coverage-relevant. #### Option B: Add Meaningful Coverage Investigate why each exact missing line is not covered. Prefer real coverage when the uncovered line represents product behavior that should keep working. Good candidates for tests: - Pure functions, parsers, config decisions, path computations, generated text decisions, and error handling. - Integration/codegen behavior where the missing line affects generated files or public workflow behavior. - Regression-prone behavior introduced or modified by the PR. For feature behavior, default to an E2E-style regression first, especially by extending an existing `pure_dart` scenario when that can exercise the real generated workflow. Only fall back to narrower tests when the E2E route is brittle, too expensive, or cannot reach the behavior: - Add a codegen or integration test when generated output proves the behavior but a full E2E case is awkward. - Unit test the function directly when the behavior is local, stable, and not meaningfully tied to an FRB workflow. Use the relevant skills after choosing the test path: - `frb-develop-feature` for feature/bug regression coverage. - `frb-test` for selecting local test commands. - `frb-dev-env` before running FRB tests or setup commands in Tom's environment. If the behavior matters but a focused test would be brittle, very expensive, or require a product decision, summarize the exact missing lines, the suspected reason they are uncovered, and the realistic options, then ask the human which tradeoff to take. ## Verification After changing tests or ignore markers: 1. Re-read the touched files immediately before editing. 2. Commit the logical fix before long verification, following Tom's commit policy. 3. Run the focused local test command when practical. 4. Push and check the latest `codecov/patch` and `codecov/project` statuses on the new head. 5. If Codecov is still red, repeat the workflow from the latest exact report instead of reusing stale line numbers. --- name: frb-fix-main-ci description: Use when flutter_rust_bridge CI fails on the default branch/main/master, especially to distinguish ordinary CI repair from a regression introduced after a previously green default-branch commit. --- # FRB Fix Main CI Use this when CI is failing on the default branch (`main` / `master`) or on a commit that is already part of the default-branch history. ## Choose a Path Default-branch CI failures usually have two possible repair paths. Choose based on the evidence in the latest relevant run. ### Path A: Ordinary CI Repair Use this path when the failure looks like a known FRB CI shape: flaky job, generated diff, lint drift, stale generated output, dependency-order failure, or downstream symptom already covered by existing CI triage. Read `frb-fix-ci` and repair the failure directly: - Check the latest relevant run, not stale status. - Use the user's `tom-ci` skill when reading GitHub Actions job logs. - Classify flakes, generated diffs, lint drift, dependency-order failures, and propagated downstream symptoms before deep debugging. - Prefer fixing prerequisite jobs such as `Generate`, `Integrate`, or high-relevance `Generate Internal` before chasing later build/test symptoms. ### Path B: Regression Investigation Use this path when the failure is not obviously a known FRB CI maintenance issue, or when several default-branch commits/runs suggest something recently broke. A default-branch failure is often a regression. There should usually be an older default-branch commit that passed the same CI path. Study what changed between the green baseline and the red commit, then fix the source of that regression. Before writing a regression fix, answer these questions: 1. What is the failing default-branch commit and workflow run? 2. What is the nearest older default-branch commit with a green run for the same workflow or job family? 3. Which commits or merged PRs sit between the green baseline and the red commit? 4. Does the failure reproduce at the red commit but not at the green baseline, using the same `./frb_internal ...` command and the FRB dev environment rules? 5. Which source change most directly explains the regression? ## Regression Workflow 1. Capture the exact failing jobs and the first useful error from CI logs. 2. Find the newest passing default-branch run for the same workflow/job family. 3. Compare the commit range between green and red: ```bash git log --oneline --decorate .. git diff --stat .. ``` 4. If the range is broad or the culprit is unclear, bisect with the smallest meaningful reproduction command. 5. Fix the source of the regression, not just the generated or downstream symptom. 6. Add or adjust regression coverage when the bug is behavioral. For pure CI/tooling drift, document the before/after evidence in the PR. ## What Not To Do - Do not treat default-branch CI as "just rerun until green" unless logs strongly indicate infra flake. - Do not force every default-branch failure through regression bisect when `frb-fix-ci` already identifies a direct CI maintenance fix. - Do not only repair checked-in generated files if the generator, template, version pin, or environment change is the real source. - Do not chase downstream job failures while an upstream generation or integration job is still red. - Do not assume the newest red commit is the sole cause without checking the nearest green baseline and intervening changes. ## PR Expectations For a PR that fixes default-branch CI, include: - Failing commit SHA and workflow/job URL. - Nearest green baseline SHA or run, if available. - The reproduction command used locally or in Docker/Tart. - The suspected or confirmed culprit commit/PR. - Why the fix addresses the source of the regression. Use `frb-prepare-pr` before opening the PR. --- name: frb-fix-merge-conflict description: Use when resolving merge or rebase conflicts in flutter_rust_bridge, especially conflicts involving generated files after master/main changed independently from a PR branch. --- # FRB Fix Merge Conflict Use this skill before resolving merge or rebase conflicts in `flutter_rust_bridge`. ## Core Rule Resolve hand-written files semantically. Do not hand-resolve generated files as the final result. Generated conflict output should be treated as a stale artifact from two independently valid histories. After the hand-written sources are merged, regenerate the generated outputs and commit that regenerated result. ## Before Starting 1. Read the FRB environment setup instructions for the current checkout before running generation or tests. 2. Read `frb-code-generation` to choose the minimal regeneration command. 3. If the conflict is discovered through CI or PR checks, read `frb-fix-ci` before deeper investigation. 4. Make sure the worktree starts clean except for the merge/rebase conflict you are intentionally resolving. ## Classify Conflicts List unmerged files: ```bash git diff --name-only --diff-filter=U ``` Classify each file into one of these buckets: | Bucket | Examples | Resolution | |--------|----------|------------| | Hand-written source | Rust APIs, codegen logic, Dart tests, docs, configs | Resolve manually with normal semantic merge | | Generated output | `frb_generated.*`, `*.freezed.dart`, `*.g.dart`, generated API wrappers, generated test entrypoints | Pick one side only as a temporary placeholder, then regenerate | | Ambiguous generated-like output | lockfiles, copied template outputs, integrate scaffolds | Confirm source of truth before choosing; use `frb-fix-ci` dependency graph if unsure | Do not use the generated-file shortcut for hand-written files merely because they are noisy. ## Generated File Conflict Workflow When a generated file conflicts because both base and PR independently added tests or APIs: 1. Resolve all hand-written source conflicts first. 2. For each generated conflicted file, choose a conflict-free placeholder from either side. The chosen side is not the final answer; it only clears conflict markers so the generator can run. 3. Stage those placeholder generated files. 4. Run the appropriate generation command from `frb-code-generation`. For broad PR-vs-master generated drift, prefer: ```bash ./frb_internal precommit-generate ``` For `frb_example/pure_dart` and `frb_example/pure_dart_pde` conflicts, the internal generator and package codegen cover different outputs. If the merge touches generated test entrypoints, copied PDE files, or the pure-Dart chain, run: ```bash ./frb_internal generate-internal-frb-example-pure-dart ``` If the merge also brings in hand-written Rust or Dart API changes, run package codegen after the internal generator: ```bash ./frb_internal generate-run-frb-codegen-command-generate --package frb_example/pure_dart ./frb_internal generate-run-frb-codegen-command-generate --package frb_example/pure_dart_pde ``` Do not stop after the internal generator when CI errors mention missing methods on generated Dart APIs such as `RustLibApi`; that usually means the package `frb_generated.*` files are stale. 5. Inspect the regenerated diff. The final generated files should reflect both sides' hand-written sources. 6. Commit the merge/rebase resolution. ### Placeholder Commands For a normal `git merge master` into a PR branch, this is usually enough for generated paths: ```bash git checkout --ours -- git add ``` For a `git rebase`, remember Git reverses the intuitive meaning of ours/theirs: `--ours` is the branch being rebased onto, and `--theirs` is the replayed commit. Since generated files are only placeholders, either side can be acceptable if the file still exists and regeneration will overwrite it. When deletion/addition is involved, prefer the side that leaves the path in the shape expected by the generator, then verify after regeneration. ## Validation After regeneration: ```bash git diff --check git diff --name-only --diff-filter=U git status --short ``` Then run the relevant local Docker-backed checks from the project skills. For broad generated-file conflict repairs, start with the same generation command CI would run, then use CI to validate the full matrix. If CI later reports more generated diff, add the experience back to this skill so the next repair has a sharper rule. ## Commit Shape Keep the conflict-resolution commit focused: - Include semantic hand-written conflict resolutions. - Include regenerated outputs from the chosen generation command. - Do not include unrelated cleanup. - Mention the generation command in the commit message body when useful. --- name: frb-issue-to-green-pr description: "Use when implementing a GitHub issue, bug fix, or feature in flutter_rust_bridge end-to-end: develop the change, add regression coverage, prepare and open a PR, and use the user's tom-ci skill to monitor CI until the PR is ready." --- # FRB Issue to Green PR Use this skill as the top-level workflow when the user asks you to implement an issue, fix a bug, add a feature, or otherwise "handle it end to end" in `flutter_rust_bridge`, especially when they ask for an automatic PR or CI monitoring. This skill orchestrates the narrower FRB skills. Do not duplicate their detailed instructions in memory; read them when their phase begins. ## Required Subskills Always read these first: 1. `frb-dev-env` and any applicable user-level environment rules. 2. `frb-develop-feature` for the reproduce -> fix -> final regression workflow. Read these when entering the matching phase: - `frb-code-generation` before running generation or changing Rust APIs, codegen, or example APIs. - `frb-test` before running local tests. - `frb-lint` before lint or format checks. - `frb-prepare-pr` before pushing or opening the PR. - `frb-pr-review` before treating a non-trivial PR as ready. - `frb-fix-ci` before diagnosing any CI failure. - The user's `tom-ci` skill for CI waiting, status inspection, and GitHub Actions logs. - `frb-manual-test` before writing a manual regression test report under `tools/manual_tests/`. - `frb-ci-filter` before creating an intentional red CI reproduction PR or using filtered CI. - `frb-debugging` when generated code is surprising or codegen behavior is unclear. ## Workflow ### 1. Start the completion loop - Keep the task active until all stop conditions are met. - Once the PR URL is known, follow the waiting workflow in the user's `tom-ci` skill between CI processing actions until the PR is ready. ### 2. Understand the GitHub issue or requested change - Fetch the issue body and comments if the user gave an issue link or number. - Identify the smallest observable failing behavior or missing capability. - Check `git status --short` and do not disturb unrelated user or multi-agent changes. ### 3. Reproduce the issue in an independent reproduction PR - Read and follow the reproduction parts of `frb-develop-feature`. - For bug fixes, do this before changing fix code or opening the fix PR. - Create an independent reproduction PR whose only purpose is to prove the bad behavior. The branch name, PR title, and PR body must say clearly that it is an intentional reproduction PR, not a real fix PR. - For intentional red CI reproduction PRs, use the title `Reproduce ISSUE_SUMMARY with intentional red CI`. - For manual-test reproduction PRs, use the title `Add manual reproduction for ISSUE_SUMMARY`. - If CI can reproduce the bad behavior, read `frb-ci-filter` and make the reproduction PR an intentional red CI PR: unchanged fix code, minimal reproducer or workflow adjustment, mandatory focused `ci_filter` run, and a failure whose error matches the user's report. - If CI cannot realistically reproduce the bad behavior, read `frb-manual-test` and make the independent reproduction PR add or update `tools/manual_tests/NAME.md` with a normal manual test procedure and mechanical execution steps an agent or human can run. - Do not proceed to the fix PR until the reproduction PR exists and has either a matching red CI run or a precise manual test report. - Save the reproduction PR URL, red CI run URL when applicable, job name or manual-test path, and matching error text for the fix PR reproduction report. ### 4. Fix the issue - Read and follow the fix, iteration, local verification, regression coverage, and final placement parts of `frb-develop-feature`. - Implement the smallest change that fixes the reproduced behavior. - Add final regression coverage with the fixed behavior as the expected result. - Make atomic commits as soon as each completed logical unit is written; do not wait until the end of the task. - Stage only files intentionally changed for this task. - Always create a new commit unless the user explicitly asks to amend. - Before considering the change ready, explicitly pass the `frb-develop-feature` Final Placement Gate: final regression coverage belongs in `frb_example/pure_dart` with generated `pure_dart_pde` coverage, not only in `frb_example/dart_minimal`. - Keep generated-file edits produced by the appropriate generator, not by hand. ### 5. Prepare and open the PR - Follow `frb-prepare-pr`. - Re-check that no final regression or feature coverage remains only in `frb_example/dart_minimal`. If it does, stop PR preparation and migrate it to `frb_example/pure_dart` first. - Push with upstream tracking. - Before drafting a PR title, inspect the user's recent PR titles and mimic the repo style. - Create the PR according to the active PR workflow and repository/user PR body rules. - If the work comes from a GitHub issue, ensure the PR body includes the appropriate closing keyword such as `Close #1234`, unless the active PR workflow explicitly requires an empty body. ### 6. Run the review gate - Follow `frb-pr-review` for the full PR review gate, including correctness review and test-weakening review. ### 7. Monitor CI until terminal - After the PR is opened or updated, do not leave the PR in an unknown queued or in-progress state. - On each wake-up, inspect the latest PR checks, not stale runs. - For bug-fix PRs with an intentional red CI reproduction PR, explicitly find the same job family or CI path that failed in the reproduction branch and verify that it is now green on the fix PR. - For bug-fix PRs with a manual-test report PR, state whether the manual regression was re-run, who or what ran it, and whether the observed behavior now matches the fixed expectation. - If CI fails, read `frb-fix-ci` and the user's `tom-ci` skill, diagnose the latest relevant failure, fix it, commit, push, and continue monitoring. - If CI appears flaky, rerun only failed jobs when appropriate, then keep monitoring. ### 8. Stop only when ready - The PR checks are green or all remaining non-green checks are clearly unrelated and explained. - The branch is pushed, commits are present on the PR, and the final status is reported to the user with the PR URL. ## Automation Rules - Follow the user's `tom-ci` skill to wait on the PR URL after each push, rerun, or handled CI event. - Treat its return as a wake-up signal, not a CI verdict. Inspect the reported checks, fix or rerun as required, then call the waiter again. - Do not add a separate time-based heartbeat or detached polling loop for the same PR. - Stop invoking the waiter once the stop conditions are met. ## Failure Handling - If blocked by permissions, missing credentials, a required external reviewer delay, or unavailable infrastructure, explain the concrete blocker and keep the PR state explicit. - If a CI run is queued for a long time, continue bounded waits using the user's `tom-ci` skill. - If new user instructions arrive, let the newest instruction steer the workflow while preserving already-completed work. --- name: frb-lint description: Use when you need to run lint, format, or clippy checks in flutter_rust_bridge --- # FRB Lint > **Note:** Read `frb-dev-env` before running commands and follow the active user's environment rules. ## Quick Reference | Command | Description | |---------|-------------| | `./frb_internal lint --fix` | Run all lints and auto-fix (recommended) | | `./frb_internal lint` | Run all lints | | `./frb_internal lint-dart` | Dart only | | `./frb_internal lint-rust` | Rust only | ## What Lint Includes It contains: - `dart analyze` - `dart format` - `cargo clippy` - `cargo fmt` # Manual Test Execution ## Test :::info Identify the manual test that was executed and why this run happened. Copy the purpose from the test report or summarize it in one sentence. ::: - Manual test: `TODO: tools/manual_tests/name.md` - Purpose: `TODO: short description copied or summarized from the test report` - Source context: `TODO: issue, PR, release, or request if relevant` ## Run :::info Record when, by whom, and against exactly what commit or release the manual test was executed. Include enough environment detail for someone else to compare results. ::: - Date and timezone: `TODO: YYYY-MM-DD HH:MM TZ` - Executor: `TODO: human, agent, or automation` - Commit or release tested: `TODO: sha or version` - Environment: `TODO: OS, shell, device, simulator, browser, or service summary` ## Procedure :::info Record whether the written test was followed exactly. Any deviation matters, even if the result passed. Include exact commands or a path to a command script when the run used one. ::: - Followed report revision: `TODO: commit containing the manual test report` - Command script or exact commands: `TODO: path to script, inline commands, or not applicable` - Deviations from written steps: `TODO: none, or list exact deviations` - Cleanup completed: `TODO: yes/no; explain if no` ## Result :::info Use `pass`, `fail`, `blocked`, or `partial`. The summary should explain the result without requiring the reader to open logs first. Include exact command exit status and concrete pass/fail indicators from the logs. ::: - Status: `TODO: pass/fail/blocked/partial` - Summary: `TODO: one or two sentences` - Command results: `TODO: each required command with exit status` - Evidence lines: `TODO: exact success/failure strings, log line numbers, or grep output proving the result` ## Artifacts :::info Link or name the artifacts captured during execution. Use `not applicable` for artifact types that do not apply. ::: - Execution markdown gist: `TODO: gist URL if this result belongs to a PR, issue, or release checklist; otherwise not applicable` - Terminal log: `TODO: path or link` - Screenshot or recording: `TODO: path or link, or not applicable` - Generated artifacts: `TODO: path or link, or not applicable` - Environment evidence: `TODO: exact tool versions, device/simulator name and UDID, browser version, or not applicable` - Cleanup evidence: `TODO: final git status, VM/container/device state, cleanup command output, or not applicable` - Other evidence: `TODO: path, link, log excerpt, or not applicable` ## Follow-up :::info If the result is not a clean pass, state the next action. Link the issue or PR when one exists. ::: - Required follow-up: `TODO: none, issue link, PR link, or next action` - Notes: `TODO: anything future executors should know` --- name: frb-manual-test description: Use when adding, executing, reviewing, or updating flutter_rust_bridge manual test reports under tools/manual_tests for scenarios that require human or agent-driven manual verification. --- # FRB Manual Test Use this skill for manual test reports in `tools/manual_tests/`. These reports describe repeatable checks that a human or agent can execute when automated tests are insufficient, unavailable, too expensive, or not the right interface for the behavior being verified. Manual tests are normal software-engineering test artifacts. They may cover devices, host-specific setup, interactive UI behavior, credentials or account state, release packaging, marketplace flows, external services, or long-running workflows. They are not tied to any single PR workflow. ## Add Manual Tests Manual test reports live under: ```text tools/manual_tests/NAME.md ``` When adding a report, do not start from a blank file. Copy the bundled test template first: ```bash cp .claude/skills/frb-manual-test/test-template.md tools/manual_tests/NAME.md ``` Use a short kebab-case name. Include a date prefix when the report is an example, a one-off check, or does not yet have a stable feature name, such as: ```text tools/manual_tests/2026-06-06-some-scenario.md ``` After copying, edit the report in place: - Replace every placeholder. - Remove sections that truly do not apply. - Keep commands and UI actions mechanical enough that a future human or agent can run them without the original conversation. - Prefer repo tooling such as `./frb_internal` when possible. - Do not rely on "run the app normally", "check manually", or "verify it works" without concrete commands or UI actions. - If credentials or private services are needed, name the required capability without including secrets. The detailed content requirements live in `test-template.md`; keep that template as the source of truth for report shape. ## Execute Manual Tests When executing a manual test, first read the target report under `tools/manual_tests/` and follow its preparation, steps, expected result, failure criteria, troubleshooting, and cleanup sections. Before reporting the run result, use the bundled execution template: ```bash cp .claude/skills/frb-manual-test/execution-template.md EXECUTION_RESULT_PATH.md ``` Always fill out an execution markdown file before summarizing the result. Do not only say that the test "passed". Execution markdown is a run artifact, not a repository test definition. Do not create it under `tools/manual_tests/` or anywhere else inside the `flutter_rust_bridge` repository. Put it in an external artifacts location such as `/private/tmp`, `~/main/artifacts/flutter_rust_bridge/`, or another run-specific artifact directory. Execution markdown must contain precise, audit-ready evidence that proves what ran and why it passed, failed, or blocked. Include the exact commands, exit status, key success or failure log lines, relevant version output, selected device or simulator identifiers, generated artifact paths, final cleanup state, and links or paths to complete logs. For successful runs, quote or summarize the concrete pass indicators such as `All tests passed!`, `test result: ok`, artifact paths, simulator UDIDs, or final `git status --short` output. Avoid vague summaries like "worked", "passed", or "looked good" without evidence. If the execution result belongs to a PR, issue, release checklist, or other reviewable workflow, upload the filled execution markdown and all review-relevant artifacts as a GitHub gist and link that gist in the PR description, PR comment, issue comment, or release checklist. Review-relevant artifacts include screenshots, recordings, logs, generated result files, and browser/device evidence needed to judge the result. The local execution markdown and artifact copies should still be kept in the run artifacts directory so the run can be audited without relying only on chat history. If the result belongs only in chat, still fill out the execution markdown locally and include its path in the chat response. Run cleanup from the manual test report before declaring the execution complete, unless cleanup is intentionally skipped and documented in the execution record. ### Reviewable Workflow Gate Before creating or updating a PR, issue comment, release checklist, or any other reviewable artifact that cites a manual test execution: 1. Fill out the execution markdown file locally. 2. Collect every artifact needed by the manual test's `Results To Capture` section, especially screenshots, recordings, logs, and generated evidence files. 3. Upload the execution markdown and those review-relevant artifacts into the same GitHub gist. Use a gist git clone and push when binary artifacts such as PNG screenshots need to be included. 4. Copy the gist URL into the execution markdown's `Execution markdown gist` field if practical. 5. Make the execution markdown point to the gist-contained artifact filenames, embedding screenshots or linking recordings when useful. 6. Link the gist URL in the reviewable artifact. 7. Keep local artifact paths only as supplemental audit evidence; they are not a substitute for gist-contained artifacts. Do not say that a PR-linked manual test execution is complete while any review-relevant artifact exists only as a local path. If gist upload or GitHub access fails, report the manual test execution as complete locally but the PR/update step as blocked until a gist containing the execution markdown and review-relevant artifacts can be created and linked. # Manual Test Template ## Purpose :::info Write one or two concrete sentences explaining what behavior this manual test verifies. Name the user-visible behavior, platform, package, or workflow under test. Do not leave this as a generic phrase like "verify it works". ::: TODO: Write what this test verifies. ## Source :::info Link the reason this test exists: issue, PR, feature request, release checklist, user report, or maintenance task. If there is no external link, state the local context in plain text. ::: - Context: `TODO: issue, PR, feature, release, or user report` - Related docs or skills: `TODO: paths or links` ## When To Run :::info State the trigger for this manual test. Examples: before a release, after changing a named subsystem, after upgrading Flutter/Rust/Dart, before closing a bug, or when validating a specific platform. ::: TODO: Write when this test is required or useful. ## Preconditions :::info List everything that must already be true before starting. Include checkout state, expected branch family if relevant, submodules, generated files, devices, simulators, credentials, account state, network access, and external services. Never paste secrets. Keep this section about reusable requirements, not one particular run. ::: - Repository: `fzyzcjy/flutter_rust_bridge` - Required checkout state: `TODO: clean checkout with submodules initialized, generated files present, etc.` - Required credentials or account state: `TODO: required capability, never paste secrets` - Required device or simulator state: `TODO: device must be available, app uninstalled, cache reset, etc.` ## Environment :::info Record exact versions and runtime context needed to make the result reproducible. If a tool is not required, write `not required` instead of leaving it ambiguous. ::: - OS: `TODO: macOS / Linux / Windows version, or not constrained` - Flutter: `TODO: flutter --version, or not required` - Dart: `TODO: dart --version, or not required` - Rust: `TODO: rustc --version, or not required` - Device or simulator: `TODO: device name, OS version, UDID if applicable, or not required` - Browser or external service: `TODO: name and version if applicable, or not required` ## Preparation :::info Give copy-pasteable commands that take an existing repository root to the state needed by the test. Prefer repository tooling such as `./frb_internal`. If generated files, caches, or dependencies are required, include the exact commands here. Keep source acquisition and revision selection outside the reusable test case. ::: ```bash git submodule update --init --recursive ``` If this test needs generated output or dependencies, list the exact setup commands here. ```bash ./frb_internal --help ``` ## Test Data :::info Describe all inputs and fixtures. Include paths, account setup, generated files, sample API code, reset commands, or "none" if the test uses no special data. ::: - Input files, API examples, account fixtures, or generated assets: `TODO: paths or setup notes, or none` - Reset procedure before each run: `TODO: commands or UI actions` ## Steps :::info Write ordered mechanical steps. Each step should be executable by a human or agent without guessing. For UI steps, name buttons, screens, field values, and expected intermediate state. For command steps, include complete commands. ::: 1. TODO: Prepare the target package, example, device, account, or service. ```bash TODO_COMMAND ``` 2. TODO: Run the command or manual action that verifies the behavior. ```bash TODO_COMMAND ``` 3. If UI interaction is required, describe each click, field value, device action, or expected screen by name. ## Expected Result :::info Define the pass condition as observable output: command exit status, log text, generated artifact, UI state, screenshot content, or external service state. Avoid vague language. ::: TODO: The command or manual flow should complete successfully and show the expected observable behavior. ```text TODO: success output, UI text, artifact path, or other pass criteria ``` ## Failure Criteria :::info List concrete conditions that mean the test failed or is blocked. Include setup failures that should be reported separately from product failures. ::: The test fails if any of the following happens: - The command exits non-zero unexpectedly. - The UI, artifact, or log output does not match the expected result. - The required device, account, or service state cannot be prepared. ## Results To Capture :::info Say exactly what artifacts the executor should save or link in the execution record. Include terminal logs, screenshots, recordings, generated files, device details, run URLs, or external service observations. ::: - Full terminal log from the command. - Screenshot or screen recording if UI behavior is involved. - Device, simulator, or browser version. - Any generated artifact path needed to inspect the result. ## Troubleshooting :::info Provide known recovery steps for common environment and setup failures. This section should help distinguish a blocked manual run from a real product failure. ::: - If dependencies are missing, re-run the repository setup commands and record the exact failure. - If a device or simulator is unavailable, record the discovered devices and mark the run as blocked. - If credentials or external services are unavailable, record the missing capability without exposing secrets. ## Cleanup :::info List commands and manual actions needed to restore the checkout, stop services, reset devices, and undo external account state. If no cleanup is needed, say so explicitly. ::: ```bash git status --short ``` Remove temporary local files, stop simulators or servers started for the test, and restore any external account or device state changed during the run. ## Future Automation :::info Explain whether this manual test could later become automated. If yes, name the likely CI job, package, or test harness. If no, explain what keeps it manual. ::: If this scenario later becomes reliable and affordable to automate, replace or supplement this manual report with an automated test and link the PR here. --- name: frb-pr-chain-split description: Use when an FRB PR contains independently landable work that should be extracted into predecessor PRs and connected as a GitHub PR chain without wasting full automatic CI. --- # 1 When to use - Use this skill while developing or reviewing a `flutter_rust_bridge` PR when part of its diff is independent of the PR's stated objective. - Split the independent work proactively. Do not wait for the user to notice the mixed scope. - Treat a change as independently landable when it: - has a coherent behavior or maintenance objective of its own; - can be implemented and validated against the current default branch; - does not require the main task's API, schema, generated output, or version change; - leaves the main PR smaller and easier to review. - Keep inseparable companion changes in the main PR. Generated snapshots, tests, and documentation required by the main change are not independent merely because they touch different files. # 2 Choose the chain boundary Classify every suspicious change before moving commits: | Classification | Destination | Reason | | --- | --- | --- | | Independent bug fix or hardening | Predecessor PR | It can land and provide value before the main task | | Independent mechanical refactor | Predecessor PR | It removes review noise from the main task | | Main-task prerequisite with its own contract | Predecessor PR | The main PR can depend on a separately reviewable foundation | | Generated output caused by the main task | Main PR | It cannot land meaningfully by itself | | Test or documentation for the main behavior | Main PR | Splitting would separate the contract from its implementation | - Prefer the smallest coherent predecessor, not the smallest textual diff. - Create several predecessor PRs when the extracted work contains multiple independent contracts. - Order predecessors by dependency. Do not infer order from commit timestamps. # 3 Build each predecessor - Fetch the canonical default branch before creating branches. - Create the first predecessor from the current default branch. - Create each later predecessor from the preceding predecessor branch. - Reconstruct the coherent final delta. Do not blindly cherry-pick commits that mix predecessor and main-task changes. - Include the predecessor's own tests and documentation. - Validate the predecessor independently before pushing. - Read `frb-prepare-pr` for generation, lint, test, and review requirements. - Use one branch and one PR per independently landable unit. - Push every chain branch to the same repository as the main PR. GitHub cannot use an unpushed local branch as a PR base. # 4 Construct the GitHub PR chain - Build a stacked branch chain, not sibling PRs that all target the default branch: ```text master <- predecessor-a <- predecessor-b <- main-task ``` - Use GitHub's official `github/gh-stack` extension through `gh stack`. - Use `gh stack` for every stack operation: initialization, restructuring, linking, submission, synchronization, rebasing, pushing, and verification. - Never construct or maintain a stack with `gh pr create --base`, `gh pr edit --base`, direct API base edits, or branch ancestry alone. - Git commands may prepare the commits and linear branch ancestry, but the result is not complete until `gh stack` creates or updates the native GitHub stack object. - Check and install the extension when necessary. The extension requires `gh` 2.0 or later; a missing `gh stack` command normally means the extension is absent, not that core `gh` is outdated. ```bash gh stack --help gh extension install github/gh-stack ``` - For an unpublished main branch, branch it directly from the final predecessor. - Initialize and submit a new local stack with `gh stack init` and `gh stack submit`. - For an already published main PR: - create a timestamped backup tag before non-trivial history work; - record the original final tree and three-dot PR diff; - restack the main branch onto the final predecessor with a fully linear history; - do not introduce merge commits because native GitHub stacks require linear ancestry; - compare the rebuilt tree and PR delta with the recorded originals before pushing; - use `--force-with-lease` only after those checks when published history must be rewritten. - Adopt existing branches or PRs with `gh stack link`. It pushes branches, creates missing PRs, corrects their base branches, and creates the native GitHub stack object. - Create and connect a new stack with commands shaped like: ```bash gh stack init --base master

gh stack submit ``` - Adopt already prepared branches or existing PRs with: ```bash gh stack link --base master

``` - Verify local ancestry, native stack metadata, and PR bases: ```bash git merge-base --is-ancestor

gh stack view --json ``` - Compare three-dot diffs after constructing the chain: - `...` contains only that predecessor; - `...` no longer contains the extracted work; - the final main-task tree is unchanged except for intentional cleanup. # 5 Conserve CI on predecessor PRs - Read `frb-ci-filter` before manipulating CI. - Immediately add `ci-manual-dispatch` after creating every predecessor PR: ```bash gh pr edit --add-label ci-manual-dispatch ``` - Add the label even when local validation is already green. Predecessor PRs must not spend the full CI matrix merely because they were split for reviewability. - The label action triggers a new `pull_request:labeled` run. The workflow concurrency group cancels the earlier automatic PR run, and the labeled run produces an empty heavy-job plan. - Do not dispatch GitHub CI when local validation is sufficient. - When a predecessor specifically needs GitHub-only evidence: - keep `ci-manual-dispatch` on the PR; - validate the filter locally; - dispatch only the smallest relevant job or matrix entry. ```bash ./frb_internal plan-ci --filter '' gh workflow run ci.yaml --ref -f 'ci_filter=' ``` - Do not treat filtered CI as full merge-readiness evidence. - When a predecessor becomes the next PR to merge, remove `ci-manual-dispatch` and obtain the normal required CI unless the maintainer explicitly accepts narrower evidence. # 6 Completion checks - Confirm each predecessor can be reviewed without understanding the main task. - Confirm each PR's GitHub base matches its immediate predecessor branch. - Confirm Git ancestry matches the GitHub base chain. - Confirm the main PR diff excludes all extracted changes. - Confirm every predecessor PR has `ci-manual-dispatch` while it is not awaiting final full CI. - Report the PR numbers, branch order, validation performed, and any intentionally dispatched `ci_filter`. # 7 Reliability pitfalls - Do not create independent sibling PRs and merely call them a chain. - Do not substitute manual PR base edits for `gh stack link` or `gh stack submit`. - Do not treat matching branch ancestry as sufficient; verify the native stack with `gh stack view --json`. - Do not force-push a published main PR merely to make its history prettier. - Do not split generated files away from the generator or source change that owns them. - Do not leave an extracted commit duplicated in the visible main PR diff. - Do not spend full CI on every dormant predecessor. - Do not leave `ci-manual-dispatch` on the PR when claiming normal full-CI readiness. --- name: frb-pr-review description: Review a flutter_rust_bridge PR before treating it as ready, including subagent checks for correctness and test weakening. --- # 1 Human SoT # 2 FRB PR Review Use this before treating a non-trivial `flutter_rust_bridge` PR as ready, especially after CI-driven fixes, Flutter upgrades, generated drift, test changes, workflow changes, or broad merge conflict resolution. ## 2.1 Review Gate Run the following review before final readiness: 1. Review the PR diff against its base: - Spawn a subagent to review correctness. - Ask it to inspect the PR diff against the PR base. - Focus on real behavior bugs, stale generated output, incorrect CI workarounds, coverage-only changes, and unrelated drift. - Require findings with file paths, line numbers, impact, and suggested fix. - Spawn a subagent to review test weakening. - Inspect changed or deleted assertions, relaxed thresholds, new skips, ignored failures, timeout changes, and coverage exclusions. - Require a concrete justification for each reduction in coverage; restore unjustified weakening and fix the underlying failure. - If `tom-style-tests` is installed, apply its common test principles and weakening gate; use `frb-test` for FRB execution commands. - Treat unjustified skipped tests, weaker assertions, broader ignores, fake timeouts, and coverage hiding as blockers. 2. Write a concise review conclusion. - Put the conclusion in the PR description or an agent-context draft when the user asks for a Markdown artifact. - Include the subagents used, accepted findings, dismissed findings, fixes made, and remaining risks. ## 2.2 Stop Condition Do not call the PR ready until: - Correctness review has no unresolved actionable findings and test-weakening review has no unjustified weakening. - CI status is green, or remaining non-green checks are clearly unrelated and explained. --- name: frb-prepare-pr description: Use when about to create a PR or push changes in flutter_rust_bridge to ensure code generation is up to date --- # FRB Prepare for PR > **Note:** Read `frb-dev-env` before running commands and follow the active user's environment rules. ## Overview Before creating a PR, ensure generated code is up to date, lint passes, and bug fixes have a concrete reproduction report in the PR description. Before treating a non-trivial PR as ready, run `frb-pr-review`. **Core principle:** Generate → Lint → Commit → PR. > **After codegen:** Follow `frb-dev-env` and verify generated output is present in the selected worktree before reviewing the diff. ## Workflow ``` 1. Read frb-code-generation skill | +-- Run required generation commands | +-- 2. For integrate output diffs, verify templates and run precommit-integrate | +-- 3. Read frb-lint skill --> Run lint --fix | +-- 4. (Optional) Read frb-test skill --> Run relevant tests | +-- 5. For non-trivial PRs, read frb-pr-review --> Run review gate | +-- 6. For bug fixes, add the reproduction report to the PR description | +-- 7. Commit all changes | +-- 8. Create PR (follow the active user-level PR workflow) ``` ## Quick Checklist 1. [ ] **REQUIRED:** Read `frb-code-generation` skill, run commands if needed 2. [ ] **REQUIRED for integrate output diffs:** If the PR changes Flutter integrate example outputs or platform scaffolds, confirm whether `frb_codegen/assets/integration_template/` is the source that should change, then run `./frb_internal precommit-integrate` 3. [ ] **REQUIRED for copied Cargokit diffs:** If the PR changes copied `cargokit` files under `frb_example/**`, read `frb-cargokit`, then run `./frb_internal sync-cargokit-copies` 4. [ ] **REQUIRED:** Read `frb-lint` skill, run `./frb_internal lint --fix` 5. [ ] (Optional) Read `frb-test` skill, run relevant tests 6. [ ] **REQUIRED for non-trivial PRs:** Read `frb-pr-review`, run the review gate before final readiness 7. [ ] **REQUIRED for bug fixes:** PR description includes the reproduction report from `frb-develop-feature`, including baseline commit, mechanical steps, observed failure, and expected behavior 8. [ ] **REQUIRED for CI iteration branches:** Read `frb-ci-filter`, then remove `ci-manual-dispatch` and rerun normal CI if the PR used filtered CI, unless the PR is explicitly about changing CI behavior 9. [ ] Commit all changes 10. [ ] Push and create PR ## What CI Will Do CI automatically runs: - Code generation check (fails if generated code is outdated) - All tests (Rust, Dart, Flutter, Web) - Lint and format checks Run lint locally to avoid CI failures. Tests are optional locally. While iterating, it can be useful to dispatch `.github/workflows/ci.yaml` with `ci_filter` so only the relevant job family or matrix entry runs. Read `frb-ci-filter` before doing this. Do not leave `ci-manual-dispatch` on the final PR unless changing CI behavior is the actual purpose of the PR. If your PR fixes Flutter integrate example outputs and the real bug is inside the embedded `cargokit` submodule, do not stop at copied example files. Push the `cargokit` fix to `fzyzcjy/cargokit` and update the submodule ref in this repo before pushing the PR branch. If the PR changes integrate-generated example output but not `frb_codegen/assets/integration_template/`, explicitly verify that the output-only change is intentional. Most integrate scaffold behavior should be fixed in the template and regenerated, not patched only in `frb_example/**`. ## Related Skills - `frb-code-generation` - Determines which generation commands to run - `frb-lint` - Lint and format checks - `frb-test` - For local debugging when CI fails - `frb-pr-review` - PR readiness review gate - `frb-ci-filter` - Filtered CI dispatch rules - Follow the active user-level PR workflow when available; otherwise use `gh pr create` with the repository's title and body conventions. --- name: frb-publish-release description: "Publish a flutter_rust_bridge release end to end: preflight checks, changelog preparation, frb_internal release publishing, released-version polling, CI babysitting, and post-release CI verification." --- # FRB Publish Release Use this skill when preparing, publishing, or babysitting a `flutter_rust_bridge` release. ## Workflow ### 1. Preflight - Work from the repository root on the intended release branch, normally fresh `master`. If the checkout is detached but already points at the intended release commit, switch or create a local release branch from that commit before running mutating release commands; do not treat detached HEAD itself as a release blocker. - Check `git status --short --branch` and do not start publishing from a dirty tree. - Check submodules before publishing: ```bash git submodule update --init --recursive git submodule status --recursive ``` Stop if any submodule path remains uninitialized. A release built without initialized submodules can publish incomplete package contents. The release script performs the same submodule-status guard before publishing. - Treat `master` as a moving branch. Before each irreversible release phase, fetch `origin master`, confirm the current release branch or detached checkout still points at the intended latest `origin/master` commit, and re-run `git status --short --branch` to confirm there are no unexpected local changes. - Confirm the target version in `CHANGELOG.md`, root `Cargo.toml`, and `frb_dart/pubspec.yaml`. - Compute the release versions the same way `./frb_internal release` does: the top `CHANGELOG.md` version is the new version and the next release section is the old version. - Verify both old and new versions are legal before running any mutating release command. The only allowed shapes are stable SemVer `MAJOR.MINOR.PATCH` such as `2.0.0`, or beta SemVer `MAJOR.MINOR.PATCH-beta.N` such as `2.0.0-beta.1`. Use exactly `^\d+\.\d+\.\d+(-beta\.\d+)?$`. - Reject versions with any other prerelease label, build metadata, missing numeric components, leading `v`, or loose text. Stop if either old or new version fails this check. - Confirm the new version is different from the old version. - Run the publish container credential preflight before starting irreversible publish steps: ```bash .claude/skills/frb-dev-env/frb_dev_env.py docker-run-rm --with-publish-credentials -- true ``` Stop if the preflight fails. It checks GitHub CLI auth, Cargo credentials, and Dart pub credentials inside the same temporary credential layout used by release publishing. - Confirm normal CI is green for the release commit before publishing. This is the default hard gate. A narrow exception is allowed only when all of these are true: - A recent earlier commit on the same release branch has fully green normal CI. - Every commit between that green commit and the intended release commit is unrelated to the publishable packages, version sources, generated release artifacts, and `frb_internal` release logic. - The mechanical gate script below exits successfully and its output is recorded in the release notes or journal. - The agent explicitly states that it is using the exception before publishing. Run the mechanical gate from the repository root: ```bash uv run --script .claude/skills/frb-publish-release/release_ci_gate.py \ --base-green-ref \ --release-ref HEAD ``` Stop and wait for normal CI if the script reports any `BLOCK` path. The script is intentionally conservative: release-surface paths such as `Cargo.toml`, `frb_dart/pubspec.yaml`, `frb_codegen/**`, `frb_macros/**`, `frb_rust/**`, `frb_utils/**`, `frb_example/**`, `tools/frb_internal/**`, `pubspec.yaml`, `melos.yaml`, and lockfiles are not in the allowlist. Release metadata and its generated copies are allowed: `CHANGELOG.md`, `frb_dart/CHANGELOG.md`, `frb_hooks/CHANGELOG.md`, `.all-contributors-custom.yaml`, `.all-contributorsrc`, `README.md`, `frb_dart/README.md`, and `website/**`. These files are reviewed directly before publishing and do not affect package execution. Other `frb_dart/**` and `frb_hooks/**` paths remain blocked. This exception is for release metadata, docs, agent tooling, devcontainer, selected CI configuration, and other explicitly non-release paths only. ### 2. Reconcile Contributors - Before writing the release changelog, use `frb-add-contributor` to identify contributors from the target release range who may need all-contributors credit or whose human-written custom description does not cover every release-range PR. - Follow `frb-add-contributor` exactly. In particular, after determining which contributors may need to be added or have their custom descriptions extended, stop for human confirmation before editing contributor files, posting GitHub comments, triggering all-contributors, opening PRs, or merging contributor PRs. - Do not continue to changelog preparation until contributor reconciliation is complete, or confirmed unnecessary because all contributors are credited and their custom descriptions cover every third-party PR in the release range. ### 3. Write Changelog - Use `frb-write-changelog` and follow it exactly. It is the single source of truth for beta and stable changelog content, grouping, ordering, attribution, review, verification, and generated package changelog copies. Do not duplicate those rules here. - Do not publish until the human-review gate required by `frb-write-changelog` is satisfied. - The top `CHANGELOG.md` version is the source used by `frb_internal release`. - If changelog or version files changed, commit that release preparation before publishing. - Land contributor and changelog preparation commits on `origin/master` before publishing. Do not leave release preparation only on a side branch. ### 4. Pre-Publish Independent Audit - Immediately before the first irreversible publish command, delegate a read-only audit to an independent subagent that has not participated in preparing the release. - Give the subagent the intended version and the raw evidence needed to verify the work completed so far: - Current branch, exact `HEAD`, latest `origin/master`, and `git status --short --branch`. - Previous and target release versions from `CHANGELOG.md`, root `Cargo.toml`, and `frb_dart/pubspec.yaml`. - Final target changelog section, contributor reconciliation result, human changelog approval, and relevant diffs. - Submodule status, credential preflight result, and normal CI green evidence or evidence that every narrow CI-gate exception condition in Step 1 is satisfied, including successful `release_ci_gate.py` output. - Exact commands and results for any additional focused release tests that were run. These tests do not replace the normal CI gate or its defined narrow exception. - Exact one-shot publish command that will run next. - Ask the subagent to return one verdict: - `GO`: all release instructions are satisfied and the evidence is internally consistent. - `NO-GO`: list every blocker, missing artifact, ambiguity, or inconsistent result with concrete evidence. - Do not tell the subagent the desired verdict or provide only a prepared summary. Let it inspect the repository and raw command outputs independently. - Stop before publishing on `NO-GO`, an ambiguous verdict, missing evidence, or unavailable subagent capability. Resolve every blocker and run a fresh independent audit. - Treat the audit as valid only for the exact audited `HEAD`, `origin/master`, clean worktree state, evidence snapshot, and next publish command. - After a `GO` verdict, run that exact publish command without any intervening mutation. If the command changes, the worktree becomes dirty, evidence is refreshed or invalidated, or `HEAD` or `origin/master` changes, repeat the affected preflight checks and the independent audit. ### 5. Publish Use the repository release command through a temporary Docker container with publish credentials as the normal publishing path: ```bash .claude/skills/frb-dev-env/frb_dev_env.py docker-run-rm --with-publish-credentials -- ./frb_internal release ``` Run the one-shot command from a clean local `master` that tracks the latest `origin/master`. `release-update-git` uses plain `git push`, so do not run the command from a side release branch. Do not split the normal release into separate `release-update-*` or publish commands. The one-shot command is the source of truth for release sequencing: it computes old/new versions from `CHANGELOG.md`, updates checked-in versions and generated version text, updates Scoop metadata, commits and pushes the version bump, creates the GitHub release, then runs the registry publisher: ```bash .claude/skills/frb-dev-env/frb_dev_env.py docker-run-rm --with-publish-credentials -- ./frb_internal release-publish-all ``` For beta versions such as `2.13.0-beta.1`, do not require the GitHub release to be labeled as a pre-release. FRB intentionally publishes beta GitHub releases as normal GitHub releases while the package version itself remains a SemVer prerelease. `release-publish-all` publishes these packages: - `frb_codegen` -> crates.io package `flutter_rust_bridge_codegen` - `frb_macros` -> crates.io package `flutter_rust_bridge_macros` - `frb_rust` -> crates.io package `flutter_rust_bridge` - `frb_dart` -> pub.dev package `flutter_rust_bridge` - `frb_hooks` -> pub.dev package `flutter_rust_bridge_hooks` Only use a split subcommand as a recovery path after confirming which one-shot step already completed. For example, if the version bump and GitHub release already exist and only registry publication is needed, use `.claude/skills/frb-dev-env/frb_dev_env.py docker-run-rm --with-publish-credentials -- ./frb_internal release-publish-all` directly. ### 6. Check Released Versions Poll registry state with: ```bash ./frb_internal get-released-version ``` To check a target version from a checkout whose manifests have not been bumped, pass it explicitly: ```bash ./frb_internal get-released-version --version ``` The command prints JSON: ```json { "allReleased": true, "packages": [ { "registry": "crates.io", "name": "flutter_rust_bridge_codegen", "manifestVersion": "2.12.0", "releasedVersion": "2.12.0", "isReleased": true } ] } ``` Wait until every package has `isReleased: true` and `allReleased: true`. If one registry lags, keep polling with bounded waits and record the mismatched package instead of assuming the publish failed. Do not add the target version option to the mutating `release-*` subcommands; they derive their version from `CHANGELOG.md` and checked-in manifests. For beta releases, `get-released-version --version ` must verify the pub.dev `versions` list, not only pub.dev's `latest` field, because pub.dev keeps `latest` on the latest stable release when a prerelease is uploaded. ### 7. Babysit CI And Post-Release CI - Keep watching the release commit's normal CI until it is green. - After `./frb_internal get-released-version` reports `allReleased: true`, trigger `.github/workflows/post_release.yaml` for the release commit or `master`. - Babysit post-release CI until it is green. Use the user's `tom-ci` skill when reading GitHub Actions logs. - If post-release fails, classify the failure by release channel (`stable` or `unstable`) and install mode (`cargo-install`, `cargo-binstall`, `scoop`, or `homebrew`) before changing code or rerunning. ## Related Skills - `frb-write-changelog` for the release section. - `frb-fix-ci` or `frb-fix-main-ci` for CI failures. - The user's `tom-ci` skill for GitHub Actions logs.

AI Agent Protocol & Instructions

Explore Related Technologies & Topics