Patchbay

Talk to your running Flutter app the way adb talks to a device.

English | 简体中文

Use cases · Quick start · Capabilities · Architecture · Usage guide · Design

Patchbay is a typed control channel reaching into the Flutter runtime: connect to a running app from your terminal, read state with its fact source attached, invoke domain commands, drive widgets by stable ID, and pull redacted logs and screenshots.

adb looks at a device from outside the system; Patchbay looks at the runtime from inside the app. On iOS in particular, it fills in the in-app debugging surface that system tooling cannot provide.

Project status: v0.4.0, published on pub.dev; requires Dart >=3.11.0, and Flutter >=3.38.0 for the Flutter UI capabilities. The control plane is enabled only in debug / profile; the packages can take part in a release compile, but the consumer must keep the host and adapters unreachable through compile-time branching at the composition root.

Patchbay is not an adb replacement, nor a coordinate-driven black-box test framework; the complete debugging toolchain is the two of them used together.

The shortest path below runs over VM Service. For the full treatment of gates, domain commands, session discovery, and direct HTTP integration, see the usage guide (currently in Chinese).

Use the hosted package for normal integration:

dependencies:
  patchbay_flutter: ^0.4.0

patchbay_flutter re-exports the core API; for pure Dart integration use packages/patchbay instead.

The following installs the native AOT GitHub Release artifact on macOS arm64. See the installation guide for other platforms and checksum verification:

$ mkdir -p ~/.local/bin
$ curl -fL https://github.com/cr1992/patchbay/releases/download/patchbay-v0.4.0/patchbay-0.4.0-macos-arm64 \
    -o ~/.local/bin/patchbay
$ chmod +x ~/.local/bin/patchbay
$ patchbay --help

Make sure ~/.local/bin is on PATH. dart pub global activate patchbay_cli remains a compatible alternative, but it installs an app snapshot loaded by the Dart runtime, not a standalone native AOT executable; do not use it to measure native AOT startup.

When that compatibility form is required, pin it to the same package version:

$ dart pub global activate patchbay_cli 0.4.0

import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:patchbay_flutter/patchbay_flutter.dart';

void main() {
  if (!kReleaseMode) {
    final gates = PatchbayGateEvaluator(
      baseGate: () => const PatchbayGateDecision.allow(),
      consumerGate: (id) => PatchbayGateDecision.reject(
        code: 'unknownConsumerGate',
        notice: 'No consumer gate named $id.',
      ),
    );

    PatchbayFlutterServiceHost(
      applicationId: 'com.example.app',
      bridge: PatchbayFlutterBridge(gates: gates),
    ).register();
  }

  runApp(const MyApp());
}

This minimal integration already gives you identity, catalog, an empty snapshot, read-only Semantics observation, and ui.wait. Semantics actions are rejected by default; domain commands, capture, logs, and navigation each require the app to inject the corresponding capability explicitly.

When you need a stable text target, replace the existing Key with a PatchbayKey. It is a GlobalKey, so it must be cached like any ordinary GlobalKey and never reconstructed on every build():

late final PatchbayKey phoneKey = PatchbayKey.text('login.phone');

@override
Widget build(BuildContext context) => TextField(
  key: phoneKey,
  controller: phoneController,
);

Run the app and copy the VM Service URI that flutter run prints. Patchbay accepts both http(s) and ws(s) URIs:

$ flutter run
$ patchbay --ws-uri '<VM Service URI>' identity
$ patchbay --ws-uri '<VM Service URI>' catalog
$ patchbay --ws-uri '<VM Service URI>' --json snapshot

A VM Service URI usually carries authentication material — keep it out of scripts, logs, and anything you commit. Once the launcher is wired up you can drop --ws-uri entirely; see automatic session discovery. With several devices connected at once, use patchbay sessions list to see the available sessions and patchbay session use <session-id> to pin one, so later commands no longer need --session; see session selection.

UI targets in the catalog come with their current generation. Write operations that declare a caller-side generation fence (text input, for example) must carry that value, so a late command cannot land on a same-named widget that has since remounted; ui tap may omit the generation, as the host pins the generation for that operation once it has resolved the identifier:

$ patchbay --ws-uri '<VM Service URI>' ui text set login.phone <generation> '13800000000'

$ patchbay identity
$ patchbay --json snapshot
$ patchbay --wait exec example.job.run
$ patchbay ui semantics tree
$ patchbay ui tap login.submit
$ patchbay --output screen.png capture root
$ patchbay logs tail
$ patchbay repl < commands.txt

This table describes syntax shipped by this CLI. Protocol-backed rows come from repository descriptors; client and local rows remain explicit CLI declarations. It is not the runtime capability catalog; use patchbay catalog for actual availability.

Ordinary external automation sees pixels, copy, and coordinates; Patchbay sees the semantics and facts the app deliberately exposes:

• Trustworthy — state values carry their fact source, and admission, execution, and device-level completion are never conflated;
• Controlled — every command passes the base gate and its declared gate, reaching only the capabilities the app has explicitly opened;
• Stable — UI targets use stable IDs and generation fencing, rather than coordinates, tree indices, or volatile copy;
• Strippable — consumers use compile-time branching to make the host and adapters unreachable in release, leaving no runtime switch to turn them back on.

None of this is a guarantee the transport makes on the app's behalf. Domain completion, privacy redaction, release artifact scanning, and platform behavior remain the consumer's responsibility, judged against its own controllers, build chain, and real-device results. The reasoning is in the six design positions (currently in Chinese).

The CLI only ever faces one unified protocol. VM Service is the default main channel; direct HTTP is an optional channel you turn on explicitly. Inside the app, every operation passes the gates first and is then handed to the Flutter bridge, a domain adapter, or the artifact service; the real state machines, router, device SDKs, and privacy policy still belong to the app itself.

Domain DTOs, device SDKs, routing, and domain vocabulary all stay in the consumer's adapter — none of it enters these four general-purpose packages.

Long-form documents under docs/ are currently in Chinese only.

• Usage guide — installation, app integration, CLI manual, exit codes, and boundaries (in Chinese)
• Design — architecture, the six design positions, and transport selection (in Chinese)
• Core package — protocol, envelopes, gates, jobs, and blobs
• Flutter package — UI observation, operations, navigation, and capture
• CLI package — the full command set and connection safety
• Direct transport — HTTP protocol and LAN risks
• Changelog — unreleased and released changes to the API, protocol, and security behavior

MIT