Merge pull request #13 from PyBLE-dev/feature/github-example-browser

Import SHA-pinned public GitHub examples

Author: yyods

CHANGELOG.md

@@ -11,6 +11,21 @@ its annotated tag rather than from the newer branch tip.
 
 ### App source
 
+- Added a connected Files action for browsing a canonical public GitHub
+  repository without an account or token, resolving the requested ref once to
+  a displayed immutable commit SHA, and lazily browsing bounded non-recursive
+  Git trees.
+- Added exact review and separate overwrite consent for importing selected
+  ordinary lowercase `.py` files into the captured board folder. The complete
+  size-bounded, strict-UTF-8 batch is fetched before sequential PBLE/1 writes;
+  partial results identify succeeded, failed, and unattempted paths, refresh
+  Files honestly, and never auto-open or auto-run downloaded code.
+- Hardened GitHub import against redirects, unexpected hosts and object
+  identities, incomplete board listings, reconnect/session races, response
+  resource exhaustion, slow-trickle requests, and public API retry deadlines,
+  with adaptive, keyboard-accessible, localized, and golden-tested states.
+- Advanced the independently versioned app source build from `0.1.0+2` to
+  `0.1.0+3`, distinguishing this development build from TestFlight build 2.
 - Added the connected board's PBLE/1 board ID and PyBLE agent firmware version
   to Board info and retained both in the ready/running status pill, with
   localized missing-value handling, full accessibility context, and
@@ -57,8 +72,9 @@ its annotated tag rather than from the newer branch tip.
 
 ## Firmware 0.6.0 — 2026-08-21
 
-_Firmware release only. The app is versioned independently and remains
-`0.1.0+2` in this source tree._
+_Firmware release only. At release qualification, the independently versioned
+app source was `0.1.0+2`; later app-source work does not alter firmware
+v0.6.0._
 
 - Published and deployed the qualified five-profile release at
   [pyble.dev/flash](https://pyble.dev/flash): `esp32-4mb`,

README.md

@@ -43,13 +43,26 @@ The Flutter app currently provides:
   version retained in the always-visible connection status;
 - a MicroPython editor with save, run, stop, soft reboot, and live console;
 - wireless file browsing and transfer with integrity checks;
+- an optional public GitHub example browser that resolves a repository/ref to
+  an immutable commit, previews exact `.py` source-to-board paths, and imports
+  selected files into the connected Files folder only after explicit review;
 - an offline Blockly workspace with GPIO and standard MicroPython NeoPixel
   blocks, including explicit numeric GPIOs and bounded named `machine.Pin`
   identities;
 - editable beginner examples;
 - exact Blockly sidecar reopening and a bounded Python-to-blocks importer;
 - an adaptive tablet interface for portrait and landscape use; and
-- local operation without an account, analytics, or cloud dependency.
+- core editing, BLE, Files, Blocks, and Run operation without an account,
+  analytics, or cloud dependency. GitHub is the sole optional network surface;
+  its public, unauthenticated requests start only when the user opens the
+  importer.
+
+GitHub import is deliberately bounded and non-executing. It accepts a canonical
+public repository URL, lazily browses one SHA-pinned snapshot, and selects only
+ordinary lowercase `.py` files from one folder. Before any board write, PyBLE
+fetches and validates the complete batch, shows the exact destination paths,
+and asks separately before overwriting existing files. Import never creates a
+remote folder hierarchy, opens an editor document, or runs downloaded code.
 
 The iPad build is available through public TestFlight. An invited Android
 internal test is available through Google Play; this is not a public Play
@@ -113,6 +126,8 @@ This repository is intentionally a monorepo:
 - [`app/`](app/) — the Flutter tablet application;
 - [`firmware/`](firmware/) — the portable agent, board overlays, and release
   tooling;
+- [`examples/`](examples/) — clean-room, board-neutral MicroPython examples,
+  including the public GitHub-import fixtures;
 - [`docs/specifications/protocol.md`](docs/specifications/protocol.md) — the
   open PBLE/1 wire contract;
 - [`tests/`](tests/) — host, conformance, release, and HIL test runners;
@@ -136,11 +151,19 @@ shared conformance corpus, documentation, and CI atomically.
 4. For the four ESP profiles, connect the board and install with Web Serial.
    For Pico 2 W, download the verified UF2 and copy it manually to the BOOTSEL
    mass-storage volume. iPadOS cannot perform either wired provisioning step.
-5. Open PyBLE, scan for the provisioned board, connect, and run an example over
-   BLE.
+5. Open PyBLE, scan for the provisioned board, and connect over BLE.
+6. To try the optional public example importer, open the destination folder in
+   **Files**, choose **Import examples from GitHub**, enter
+   `https://github.com/PyBLE-dev/PyBLE` with ref `main`, then browse to
+   `examples/github-import`.
+7. Select `hello.py` or `count.py`, review the displayed commit SHA and exact
+   board target, and confirm any overwrite separately. Import does not open or
+   run the file; open it from Files and choose Run only when you are ready.
 
 See [support and troubleshooting](https://pyble.dev/support) for browser,
-Bluetooth, and recovery requirements.
+Bluetooth, network, and recovery requirements. A GitHub account or token is not
+needed for the optional import; every other workflow remains available without
+it.
 
 ## Build and test
 

app/DEPENDENCIES.md

@@ -36,6 +36,7 @@ Toolchain pin: **Flutter 3.44.1 (stable)** / Dart SDK `^3.12.1` (see
 | `flutter_blue_plus` | runtime | `^1.35.0` | 1.36.8 | BSD-3-Clause | The BLE transport (A-02; FR-BLE-1/2/3/5). The **sole** importer lives under `lib/ble/`; no other layer may import it (enforced by `tools/ci/import_boundary.sh`, CON-8). Min 1.35.0 is the floor carrying the GATT service-filtered scan + `requestMtu(247)` + write-without-response API the `lib/ble` adapter binds to. It is a **federated** plugin: it hard-depends on all platform backends (`_android`/`_darwin`/`_linux`/`_web`); only the Android + iOS (`_darwin`) backends compile into PyBLE's shipped targets — see the **copyleft carve-out** under the transitive table. |
 | `intl` | runtime | `^0.20.2` | 0.20.2 | BSD-3-Clause | The ARB message runtime consumed by the generated `AppLocalizations` (X-12). The constraint is reconciled to the exact `intl` the pinned `flutter_localizations` (Flutter 3.44.1) admits — 0.20.2. |
 | `package_info_plus` | runtime | `^10.2.1` | 10.2.1 | BSD-3-Clause | The sole `lib/app/app_build_info.dart` adapter reads the actual installed iOS/Android version and build number for the X-11 About page (FR-ABOUT-3). It is never imported by `lib/pble`; static ASCII `kAppVersion` remains the PBLE/1 HELLO identity. Min 10.2.1 supports PyBLE's pinned Flutter 3.44.1, Dart 3.12.1, iOS 13, Java 17, AGP 9.0.1, and Gradle 9.1 toolchain. |
+| `http` | runtime | `^1.6.0` | 1.6.0 | BSD-3-Clause | The bounded public GitHub REST client for the connected A-33 subset ([ADR-0040](../docs/decisions/0040-sha-pinned-connected-github-import.md)). The direct dependency is confined to `lib/github_import/`'s production composition point and `GithubRepositoryClient`; all feature consumers bind to the neutral `GithubApi` seam. The adapter accepts only canonical public repository input, sends no credential or user source, permits requests only to exact HTTPS host `api.github.com`, disables redirects, pins every browse to a full commit SHA, and bounds time and response bodies. Min 1.6.0 supplies the abortable request surface used by the cancellation contract on the pinned Dart/Flutter toolchain. |
 | `webview_flutter` | runtime | `^4.14.1` | 4.14.1 | BSD-3-Clause | The offline platform-WebView host for the pinned Blockly runtime (A-31, ADR-0013). Min 4.14.1 matches PyBLE's Android 24 / iOS 13 platform floors and supplies `loadFlutterAsset`, JavaScript channels, and navigation delegates. Its sole importer is `lib/blocks/`; generated source and board actions stay in Dart behind the neutral `Connection` seam. |
 | `flutter_test` | dev (SDK) | Flutter SDK | 3.44.1 | BSD-3-Clause | Widget/unit/golden test harness; the substrate for the G1 suites (NFR-MAINT-4). |
 | `integration_test` | dev (SDK) | Flutter SDK | 3.44.1 | BSD-3-Clause | On-device Android/iPadOS parity coverage for the real Blockly platform WebView, local asset load, JavaScript bridge, generated Python, and file-backed actions (A-31). Ships with the Flutter SDK and is never part of a release build. |
@@ -70,7 +71,6 @@ directly. Every one is permissive and MIT-compatible (verified against the
 | `flutter_driver` | (Flutter SDK) | BSD-3-Clause |
 | `flutter_web_plugins` | (Flutter SDK) | BSD-3-Clause |
 | `fuchsia_remote_debug_protocol` | (Flutter SDK) | BSD-3-Clause |
-| `http` | 1.6.0 | BSD-3-Clause |
 | `http_parser` | 4.1.2 | BSD-3-Clause |
 | `leak_tracker` | 11.0.2 | BSD-3-Clause |
 | `leak_tracker_flutter_testing` | 3.0.10 | BSD-3-Clause |
@@ -151,5 +151,4 @@ rationale when added:
 |---|---|---|
 | `drift`, `sqlite3` | S5 / A-24 | Local persistence. |
 | `fl_chart` | later | Plotting surface. |
-| direct `http` / `dio` client | later | Network fetch for the import flow. (`http` is currently transitive through `package_info_plus`, but PyBLE imports no network client for About and performs no metadata network request.) |
 | `go_router` | — | Not planned for S1; navigation is index-based via a Riverpod `StateProvider` + `IndexedStack`. |

app/README.md

@@ -9,6 +9,9 @@ Low Energy.
 - BLE discovery, connection, reconnect, and capability negotiation
 - Python editing, save, run, stop, soft reboot, and live console
 - Wireless filesystem browsing and integrity-checked transfer
+- Optional public, unauthenticated GitHub browsing with immutable commit
+  pinning, exact board-target review, and bounded `.py` import into the current
+  connected Files folder
 - Offline Blockly workspace with beginner examples, GPIO, and NeoPixel blocks
 - Exact Blockly sidecars and bounded Python-to-block conversion
 - Adaptive portrait and landscape layouts
@@ -17,6 +20,11 @@ Low Energy.
 The public iPad beta is available through
 [TestFlight](https://testflight.apple.com/join/yU4e8s6d).
 
+GitHub import is the app's sole optional internet workflow. It sends no account
+credential, board fact, or source file; it never auto-opens or runs imported
+code. Editing, BLE, Files, Blocks, and Run remain account-free and independent
+of GitHub availability.
+
 ## Requirements
 
 - Flutter stable matching the version pinned in root CI
@@ -40,10 +48,11 @@ Pixel goldens use reviewed macOS baselines. Run them separately on macOS:
 flutter test --tags golden
 ```
 
-Run on a connected device:
+Install a standalone development build on a connected device (the current
+source build is `0.1.0+3`):
 
 ```sh
-flutter run
+flutter run --release -d <device-id>
 ```
 
 Platform WebView integration tests live under `integration_test/`. CI runs

app/android/app/src/main/AndroidManifest.xml

@@ -19,6 +19,9 @@
     <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
     <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30" />
     <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" android:maxSdkVersion="28" />
+    <!-- User-started, public GitHub example import (A-33). This must be in the
+         main manifest so release builds can reach the exact HTTPS API host. -->
+    <uses-permission android:name="android.permission.INTERNET" />
     <application
         android:label="PyBLE"
         android:name="${applicationName}"

app/lib/app/app_info.dart

@@ -17,6 +17,6 @@ library;
 const String kAppName = 'PyBLE';
 
 /// The client version sent in HELLO (ASCII semver). Kept in step with the
-/// `version:` field in `app/pubspec.yaml` (currently `0.1.0+1`); the build-
-/// metadata suffix (`+1`) is dropped so the wire value is a clean semver.
+/// `version:` field in `app/pubspec.yaml` (currently `0.1.0+3`); the build-
+/// metadata suffix (`+3`) is dropped so the wire value is a clean semver.
 const String kAppVersion = '0.1.0';

app/lib/files/files_view.dart

@@ -8,7 +8,8 @@
 ///   * **Disconnected** — a quiet `folder_off` [EmptyState] with guidance and NO
 ///     destructive actions (nothing to act on).
 ///   * **Connected** — a breadcrumb + action bar (Up / Refresh / New file / New
-///     folder / Upload) over the live listing. Tapping a folder descends; tapping
+///     folder / Upload / GitHub import) over the live listing. Tapping a folder
+///     descends; tapping
 ///     a file opens it in the editor. Each row carries rename/delete affordances.
 ///     A determinate transfer bar shows during a transfer; a typed failure is
 ///     surfaced as an ARB-localized message (FR-FILES-3), never a raw code.
@@ -29,6 +30,8 @@ import 'package:pyble/app/providers.dart';
 import 'package:pyble/blocks/blocks.dart'
     show pythonBlocksFlowBusyProvider, showBoardFileAsBlocksConversion;
 import 'package:pyble/editor/editor.dart' show SmartPunctuationFormatter;
+import 'package:pyble/github_import/github_import.dart'
+    show showGithubImportBrowser;
 import 'package:pyble/localization/localization.dart';
 import 'package:pyble/pble/pble.dart';
 import 'package:pyble/theme/theme.dart';
@@ -56,19 +59,36 @@ class FilesView extends ConsumerWidget {
             detail: l10n.filesDisconnectedDetail,
           );
         }
-        return const _Explorer();
+        return _Explorer(connState: connState);
       },
     );
   }
 }
 
 /// The connected explorer body: action bar + transfer progress + error banner +
 /// the live listing. Reads (and thereby builds) the [fileExplorerProvider].
-class _Explorer extends ConsumerWidget {
-  const _Explorer();
+class _Explorer extends ConsumerStatefulWidget {
+  const _Explorer({required this.connState});
+
+  final ConnState connState;
 
   @override
-  Widget build(BuildContext context, WidgetRef ref) {
+  ConsumerState<_Explorer> createState() => _ExplorerState();
+}
+
+class _ExplorerState extends ConsumerState<_Explorer> {
+  final FocusNode _githubImportFocus = FocusNode(
+    debugLabel: 'Files GitHub import action',
+  );
+
+  @override
+  void dispose() {
+    _githubImportFocus.dispose();
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
     final FileExplorerState state = ref.watch(fileExplorerProvider);
     final FileExplorerController ctrl = ref.read(fileExplorerProvider.notifier);
     final bool pythonBlocksBusy = ref.watch(pythonBlocksFlowBusyProvider);
@@ -77,7 +97,22 @@ class _Explorer extends ConsumerWidget {
     return Column(
       crossAxisAlignment: CrossAxisAlignment.stretch,
       children: <Widget>[
-        _ActionBar(state: state, ctrl: ctrl, l10n: l10n),
+        _ActionBar(
+          state: state,
+          ctrl: ctrl,
+          l10n: l10n,
+          githubImportFocus: _githubImportFocus,
+          githubImportEnabled: widget.connState == ConnState.ready,
+          openGithubImport: () async {
+            await showGithubImportBrowser(
+              context,
+              ref,
+              cwd: state.cwd,
+              refreshFiles: ctrl.refresh,
+            );
+            if (mounted) _githubImportFocus.requestFocus();
+          },
+        ),
         if (state.progress != null)
           _TransferBar(
             progress: state.progress!,
@@ -107,11 +142,17 @@ class _ActionBar extends StatelessWidget {
     required this.state,
     required this.ctrl,
     required this.l10n,
+    required this.githubImportFocus,
+    required this.githubImportEnabled,
+    required this.openGithubImport,
   });
 
   final FileExplorerState state;
   final FileExplorerController ctrl;
   final AppLocalizations l10n;
+  final FocusNode githubImportFocus;
+  final bool githubImportEnabled;
+  final Future<void> Function() openGithubImport;
 
   @override
   Widget build(BuildContext context) {
@@ -173,6 +214,14 @@ class _ActionBar extends StatelessWidget {
                   icon: const Icon(Icons.upload_file_outlined),
                   onPressed: () => ctrl.uploadCurrentBuffer(),
                 ),
+                IconButton(
+                  focusNode: githubImportFocus,
+                  tooltip: githubImportEnabled
+                      ? l10n.githubImportAction
+                      : l10n.githubImportRequiresReady,
+                  icon: const Icon(Icons.cloud_download_outlined),
+                  onPressed: githubImportEnabled ? openGithubImport : null,
+                ),
               ],
             ),
           ),