mirror of
https://github.com/block/buzz.git
synced 2026-08-18 06:50:31 +02:00
f956e6fe06
## Summary - allow agents to build and run Flutter when it provides relevant implementation or validation evidence - keep mobile iteration fast by reusing simulators, incremental builds, and configured staging or production communities - correct stale CLI, E2E, CI, worktree formatting, and mobile launch guidance - point community singleton reset guidance at the canonical implementation instead of duplicating a drifting inventory ## Validation - `git diff --check origin/main..HEAD` - `cargo run -q -p buzz-cli -- --format compact messages thread --help` - `cargo run -q -p buzz-cli -- --format compact messages search --help` - `just desktop-tauri-fmt-check` from the worktree - pre-commit: mobile Dart formatting and `flutter analyze` - pre-push: branch-skew check and full mobile test suite (1,465 tests) Signed-off-by: Wes <wesbillman@users.noreply.github.com> Co-authored-by: Carl <c7ebe626f000404285d3686e1dc74cc07cc60a9754a150041ba132e14bd3e2ec@buzz.block.builderlab.xyz>
101 lines
3.6 KiB
Markdown
101 lines
3.6 KiB
Markdown
# Buzz Mobile
|
|
|
|
Flutter mobile client for Buzz.
|
|
|
|
## Setup
|
|
|
|
```bash
|
|
cd mobile
|
|
flutter pub get
|
|
```
|
|
|
|
## Run
|
|
|
|
```bash
|
|
# From repo root (applies a worktree-isolated debug identity and starts/reuses Simulator):
|
|
just mobile-dev
|
|
|
|
# Direct (uses the app's configured community; apply worktree overrides first):
|
|
cd mobile && flutter run
|
|
```
|
|
|
|
### Worktree-aware debug identity
|
|
|
|
Debug builds produced from a git worktree get a unique app identifier keyed
|
|
to the **worktree directory name** (`com.buzz.buzzMobile.<slug>` on iOS,
|
|
`xyz.block.buzz.mobile.<slug>` on Android) plus a display-only branch label
|
|
in the app name (`Buzz (my-branch)`, or a short SHA when the worktree is
|
|
detached). Because the identifier follows the directory rather than the
|
|
branch, one worktree keeps exactly one installed app — and its login state —
|
|
across branch switches, and builds from multiple worktrees install side by
|
|
side, mirroring the desktop dev experience. Release and profile builds
|
|
always keep the production identity and name.
|
|
|
|
`just mobile-dev` and `just mobile-build-android` apply this automatically by
|
|
running `scripts/mobile-worktree-overrides.sh`, which writes two gitignored
|
|
files:
|
|
|
|
- `mobile/ios/Flutter/WorktreeOverrides.xcconfig` (included by Debug builds
|
|
only; a developer's `AppOverrides.xcconfig` is included after it, so
|
|
app-specific overrides like a personal `BUNDLE_IDENTIFIER` for device
|
|
signing always win)
|
|
- `mobile/android/worktree.properties` (read by the debug build type only)
|
|
|
|
For direct Xcode / Android Studio / `flutter run` development, run
|
|
`./scripts/mobile-worktree-overrides.sh` from the repo root once per branch
|
|
switch to refresh the display label (the install identity never changes);
|
|
the persisted files are then picked up by any subsequent build. In the main
|
|
checkout the script is a no-op that removes stale override files, restoring
|
|
the plain `Buzz` identity.
|
|
|
|
To remove leftover worktree-suffixed installs from booted iOS simulators and
|
|
connected Android emulators, run `just mobile-clean` (add `--dry-run` via
|
|
`./scripts/mobile-worktree-clean.sh --dry-run` to preview). Production
|
|
installs are never touched.
|
|
|
|
## Checks
|
|
|
|
```bash
|
|
dart format --output=none --set-exit-if-changed .
|
|
flutter analyze
|
|
flutter test
|
|
```
|
|
|
|
Or from the repo root: `just mobile-check` and `just mobile-test`.
|
|
|
|
## Android release signing
|
|
|
|
Android release builds fail unless all upload-key inputs are supplied through the
|
|
environment:
|
|
|
|
- `BUZZ_ANDROID_UPLOAD_KEYSTORE_PATH`: path to a CI-vended keystore file
|
|
- `BUZZ_ANDROID_UPLOAD_KEYSTORE_PASSWORD`
|
|
- `BUZZ_ANDROID_UPLOAD_KEY_ALIAS`
|
|
- `BUZZ_ANDROID_UPLOAD_KEY_PASSWORD`
|
|
|
|
The keystore path must be absolute, and the keystore must remain outside the
|
|
repository. Development and debug builds do not require these variables.
|
|
|
|
Release pipelines that sign through the central APK Signer service instead of
|
|
a local upload keystore must set `BUZZ_ANDROID_RELEASE_SIGNING=external`. That
|
|
mode produces an unsigned release bundle and refuses to run if any
|
|
`BUZZ_ANDROID_UPLOAD_*` value is also set.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
lib/
|
|
├── main.dart # Entry point, Riverpod bootstrap
|
|
├── app.dart # MaterialApp with theme
|
|
├── shared/
|
|
│ └── theme/ # Catppuccin light/dark, spacing tokens, extensions
|
|
└── features/
|
|
└── home/ # Placeholder home surface
|
|
```
|
|
|
|
- **State management:** Riverpod + Hooks (`HookConsumerWidget`)
|
|
- **Theme:** Catppuccin Latte (light) / Macchiato (dark) — matches desktop
|
|
- **Spacing:** `Grid` tokens for consistent spacing
|
|
- **Linting:** `flutter_lints` + `riverpod_lint` via `custom_lint`
|
|
- **Feature isolation:** No cross-feature imports except `shared/`
|