Detect build readiness from webdev stdout

Switches WebdevServer from ProcessStartMode.inheritStdio to
ProcessStartMode.normal so that webdev stdout can be monitored.
Exposes a stdoutLines broadcast stream on WebdevServer; stderr
continues to be forwarded to the parent process.

ServeCommand listens to stdoutLines, forwarding each line to
stdout and watching for build_runner's completion signal
('Built with build_runner' / 'Failed to build with build_runner').
Once detected, it emits '[INFO] Succeeded after N seconds' on its
own line.

Also adds a test verifying the build-complete signal appears in
webdev stdout before the HTTP server becomes responsive.

Author: evanweible-wf

CHANGELOG.md

@@ -1,3 +1,7 @@
+## Unreleased
+
+- #67 Detect build readiness from webdev stdout for compatibility with Dart 3 / newer webdev versions.
+
 ## 0.1.12
 
 - Update ranges of dependencies so that in Dart 3 we can resolve to analyzer 6, while still working with Dart 2.19. https://github.com/Workiva/webdev_proxy/pull/46

lib/src/serve_command.dart

@@ -149,6 +149,8 @@ class ServeCommand extends Command<int> {
       for (final dir in portsToServeByDir.keys) dir: await findUnusedPort()
     };
 
+    final startupTimer = Stopwatch()..start();
+
     // Start the underlying `webdev serve` process.
     webdevServer = await WebdevServer.start([
       if (hostname != 'localhost') '--hostname=$hostname',
@@ -157,6 +159,9 @@ class ServeCommand extends Command<int> {
         '$dir:${portsToProxyByDir[dir]}',
     ]);
 
+    // Forward webdev stdout so users see build output.
+    webdevServer.stdoutLines.listen((line) => stdout.writeln(line));
+
     // Stop proxies and exit if webdev exits.
     unawaited(webdevServer.exitCode.then((code) {
       if (!interruptReceived && !proxiesFailed) {
@@ -186,6 +191,30 @@ class ServeCommand extends Command<int> {
       }
     }
 
+    if (!proxiesFailed) {
+      // Wait for build_runner to report completion via webdev's stdout.
+      // build_runner always emits one of these lines when the initial build
+      // finishes, regardless of whether -v/verbose is set.
+      const buildCompleteStrings = [
+        'Built with build_runner',
+        'Failed to build with build_runner',
+      ];
+      await Future.any([
+        webdevServer.stdoutLines.firstWhere(
+          (line) => buildCompleteStrings.any(line.contains),
+        ),
+        exitCodeCompleter.future,
+      ]);
+
+      if (!exitCodeCompleter.isCompleted) {
+        final elapsedSeconds =
+            (startupTimer.elapsedMilliseconds / 1000).toStringAsFixed(1);
+        stdout.writeln('[INFO] Succeeded after $elapsedSeconds seconds');
+      }
+    }
+
+    startupTimer.stop();
+
     return exitCodeCompleter.future;
   }
 }

lib/src/webdev_server.dart

@@ -13,6 +13,7 @@
 // limitations under the License.
 
 import 'dart:async';
+import 'dart:convert';
 import 'dart:io';
 
 import 'package:webdev_proxy/src/logging.dart';
@@ -22,7 +23,14 @@ class WebdevServer {
   /// The `webdev serve ...` process.
   final Process _process;
 
-  WebdevServer._(this._process);
+  /// A broadcast stream of lines from the `webdev serve` process stdout.
+  ///
+  /// Useful for detecting build lifecycle events such as
+  /// `'Built with build_runner'` (success) or
+  /// `'Failed to build with build_runner'` (failure).
+  final Stream<String> stdoutLines;
+
+  WebdevServer._(this._process, this.stdoutLines);
 
   /// Returns a Future which completes with the exit code of the underlying
   /// `webdev serve` process.
@@ -37,15 +45,35 @@ class WebdevServer {
 
   /// Starts a `webdev serve` process with the given [args] and returns a
   /// [WebdevServer] abstraction over said process.
-  static Future<WebdevServer> start(List<String> args,
-      {ProcessStartMode mode = ProcessStartMode.inheritStdio}) async {
-    final webdevArgs = ['pub', 'global', 'run', 'webdev', 'serve', ...args];
+  static Future<WebdevServer> start(List<String> args) async {
+    final webdevArgs = [
+      'pub',
+      'global',
+      'run',
+      'webdev',
+      'serve',
+      ...args,
+    ];
     log.fine('Running `dart ${webdevArgs.join(' ')}');
     final process = await Process.start(
       'dart',
       webdevArgs,
-      mode: mode,
+      mode: ProcessStartMode.normal,
     );
-    return WebdevServer._(process);
+
+    // Forward stderr so error messages remain visible.
+    process.stderr.listen((data) => stderr.add(data));
+
+    // Split stdout into lines and expose as a broadcast stream. The listen()
+    // call here is essential: it drains the process stdout pipe (preventing
+    // backpressure deadlock) regardless of whether anyone subscribes to the
+    // broadcast stream.
+    final controller = StreamController<String>.broadcast();
+    process.stdout
+        .transform(utf8.decoder)
+        .transform(const LineSplitter())
+        .listen(controller.add, onDone: controller.close, cancelOnError: false);
+
+    return WebdevServer._(process, controller.stream);
   }
 }

test/webdev_ready_detection_test.dart

@@ -0,0 +1,77 @@
+// Copyright 2019 Workiva Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+@TestOn('vm')
+import 'dart:async';
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:http/http.dart' as http;
+import 'package:test/test.dart';
+import 'package:webdev_proxy/src/port_utils.dart';
+import 'package:webdev_proxy/src/webdev_proc_utils.dart';
+import 'package:webdev_proxy/src/webdev_server.dart';
+
+import 'util.dart';
+
+// Matches the build-complete patterns that build_runner emits to webdev stdout.
+final _buildCompletePattern =
+    RegExp(r'Built with build_runner|Failed to build with build_runner');
+
+// Strips ANSI escape sequences so output is readable in test logs.
+String _stripAnsi(String s) => s.replaceAll(RegExp(r'\x1b\[[0-9;]*[a-zA-Z]'), '');
+
+void main() {
+  late WebdevServer webdevServer;
+
+  setUpAll(() async {
+    await activateWebdev(webdevCompatibility.toString());
+  });
+
+  tearDown(() async {
+    await webdevServer.close();
+  });
+
+  test(
+      'WebdevServer.stdoutLines emits build-complete signal before HTTP server '
+      'responds', () async {
+    final port = await findUnusedPort();
+    webdevServer = await WebdevServer.start(['test:$port']);
+
+    final allLines = <String>[];
+    webdevServer.stdoutLines.listen((line) => allLines.add(line));
+
+    String? matchedLine;
+    try {
+      matchedLine = await webdevServer.stdoutLines
+          .firstWhere(_buildCompletePattern.hasMatch)
+          .timeout(const Duration(seconds: 90));
+    } on TimeoutException {
+      fail('Timed out waiting for build-complete signal.\n'
+          'Lines seen:\n${allLines.map(_stripAnsi).map((l) => '  $l').join('\n')}');
+    } on StateError {
+      fail('Build-complete signal never appeared — webdev exited early.\n'
+          'Lines seen:\n${allLines.map(_stripAnsi).map((l) => '  $l').join('\n')}');
+    }
+
+    expect(_stripAnsi(matchedLine), matches(_buildCompletePattern),
+        reason: 'Matched line should contain the build-complete pattern');
+
+    // Verify the server is also HTTP-responsive at this point.
+    final response = await http
+        .get(Uri.parse('http://localhost:$port/'))
+        .timeout(const Duration(seconds: 10));
+    expect(response.statusCode, isNot(equals(0)));
+  });
+}

test/webdev_server_test.dart

@@ -13,8 +13,6 @@
 // limitations under the License.
 
 @TestOn('vm')
-import 'dart:io';
-
 import 'package:http/http.dart' as http;
 import 'package:test/test.dart';
 import 'package:webdev_proxy/src/port_utils.dart';
@@ -36,8 +34,7 @@ void main() async {
 
   test('Serves a directory', () async {
     final port = await findUnusedPort();
-    webdevServer =
-        await WebdevServer.start(['test:$port'], mode: ProcessStartMode.normal);
+    webdevServer = await WebdevServer.start(['test:$port']);
 
     // We don't have a good way of knowing when the `webdev serve` process has
     // started listening on the port, so we send a request periodically until it