30ba70ade8
Guide new users through connecting a server, configuring an agent harness, starting runs, and chatting with agents. Persist completion per device and offer the walkthrough again for empty servers or from Settings, with widget coverage and implementation notes.
201 lines
6.1 KiB
Dart
201 lines
6.1 KiB
Dart
import 'dart:async';
|
|
|
|
import 'package:flutter/widgets.dart';
|
|
|
|
import '../../core/api_gateway.dart';
|
|
import 'first_run_walkthrough.dart';
|
|
import 'walkthrough_store.dart';
|
|
|
|
/// Reports whether the server has no pipelines, runs or chats yet. Returns null
|
|
/// when any of the three lists cannot be read, so an unreadable server never
|
|
/// triggers the walkthrough.
|
|
Future<bool?> serverHasNoWorkYet(ApiGateway? gateway) async {
|
|
if (gateway == null) return null;
|
|
try {
|
|
final replies = await Future.wait(<Future<JsonMap>>[
|
|
gateway.call('list_pipelines', {'include_archived': true}),
|
|
gateway.call('list_runs'),
|
|
gateway.call('chat_sessions'),
|
|
]);
|
|
final lists = <Object?>[
|
|
replies[0]['pipelines'],
|
|
replies[1]['runs'],
|
|
replies[2]['chat_sessions'],
|
|
];
|
|
if (lists.any((list) => list is! List)) return null;
|
|
return lists.every((list) => (list as List).isEmpty);
|
|
} catch (_) {
|
|
return null;
|
|
}
|
|
}
|
|
|
|
/// Offers the walkthrough from the Pipelines page, which is the first screen a
|
|
/// new user sees. It is offered when:
|
|
///
|
|
/// * the device has not finished or skipped it yet (first launch, once); or
|
|
/// * the device already has, and the connected server has no pipelines, runs
|
|
/// or chats, and that server has not been offered it before.
|
|
///
|
|
/// The server check needs a connected session. While disconnected it waits, and
|
|
/// it runs again on each new connection until the server answers. A check that
|
|
/// cannot read the server leaves the gate open to retry; a decided check (the
|
|
/// walkthrough shown, or the server has work) ends it for this mount.
|
|
///
|
|
/// Nothing is shown while the store cannot be read, because an unavailable
|
|
/// store reports "seen". The check runs only while [enabled] (the Pipelines tab
|
|
/// is the one showing).
|
|
class FirstRunWalkthroughGate extends StatefulWidget {
|
|
const FirstRunWalkthroughGate({
|
|
super.key,
|
|
required this.child,
|
|
required this.store,
|
|
required this.enabled,
|
|
required this.serverScope,
|
|
required this.connection,
|
|
required this.connected,
|
|
this.gateway,
|
|
});
|
|
|
|
final Widget child;
|
|
final WalkthroughStore store;
|
|
|
|
/// Whether the Pipelines page is the one showing.
|
|
final bool enabled;
|
|
|
|
/// The connected server's scope, recorded when the walkthrough is offered.
|
|
final String serverScope;
|
|
|
|
/// Notifies when the connection may have changed; the gate re-reads
|
|
/// [connected] on each notification.
|
|
final Listenable connection;
|
|
|
|
/// Whether the server session is connected right now.
|
|
final bool Function() connected;
|
|
|
|
/// The connected server's gateway, used for the empty-server check.
|
|
final ApiGateway? gateway;
|
|
|
|
@override
|
|
State<FirstRunWalkthroughGate> createState() =>
|
|
_FirstRunWalkthroughGateState();
|
|
}
|
|
|
|
class _FirstRunWalkthroughGateState extends State<FirstRunWalkthroughGate> {
|
|
/// The offer is decided for this mount: shown, or nothing left to offer.
|
|
bool _decided = false;
|
|
|
|
/// An offer is in flight.
|
|
bool _running = false;
|
|
|
|
/// A new connection arrived while an offer was in flight.
|
|
bool _connectedAgain = false;
|
|
late bool _wasConnected;
|
|
|
|
@override
|
|
void initState() {
|
|
super.initState();
|
|
_wasConnected = widget.connected();
|
|
widget.connection.addListener(_onConnectionChanged);
|
|
_scheduleIfEnabled();
|
|
}
|
|
|
|
@override
|
|
void didUpdateWidget(FirstRunWalkthroughGate oldWidget) {
|
|
super.didUpdateWidget(oldWidget);
|
|
if (oldWidget.connection != widget.connection) {
|
|
oldWidget.connection.removeListener(_onConnectionChanged);
|
|
widget.connection.addListener(_onConnectionChanged);
|
|
}
|
|
_scheduleIfEnabled();
|
|
}
|
|
|
|
@override
|
|
void dispose() {
|
|
widget.connection.removeListener(_onConnectionChanged);
|
|
super.dispose();
|
|
}
|
|
|
|
/// Acts only on a disconnected-to-connected transition, so frequent session
|
|
/// notifications while connected never repeat the server check.
|
|
void _onConnectionChanged() {
|
|
final connected = widget.connected();
|
|
final became = connected && !_wasConnected;
|
|
_wasConnected = connected;
|
|
if (!became || _decided) return;
|
|
if (_running) {
|
|
_connectedAgain = true;
|
|
return;
|
|
}
|
|
_scheduleIfEnabled();
|
|
}
|
|
|
|
void _scheduleIfEnabled() {
|
|
if (_decided || _running || !widget.enabled) return;
|
|
_running = true;
|
|
// A connection can arrive between frames; the post-frame callback needs a
|
|
// frame, so request one explicitly.
|
|
WidgetsBinding.instance.addPostFrameCallback((_) {
|
|
if (!_active) {
|
|
// Pipelines is hidden (or the gate is gone): release the flag so a
|
|
// later enable reschedules the offer through didUpdateWidget.
|
|
_running = false;
|
|
return;
|
|
}
|
|
unawaited(_runOffer());
|
|
});
|
|
WidgetsBinding.instance.ensureVisualUpdate();
|
|
}
|
|
|
|
/// The gate may offer only while mounted and while the Pipelines page is the
|
|
/// one showing. Checked after every await and before every show.
|
|
bool get _active => mounted && widget.enabled;
|
|
|
|
Future<void> _runOffer() async {
|
|
try {
|
|
await _offer();
|
|
} finally {
|
|
_running = false;
|
|
final again = _connectedAgain;
|
|
_connectedAgain = false;
|
|
if (again && !_decided) _scheduleIfEnabled();
|
|
}
|
|
}
|
|
|
|
Future<void> _offer() async {
|
|
final seen = await widget.store.isSeen();
|
|
if (!_active) return;
|
|
if (!seen) {
|
|
_decided = true;
|
|
await _showIfActive();
|
|
return;
|
|
}
|
|
if (await widget.store.wasOffered(widget.serverScope)) {
|
|
if (!_active) return;
|
|
_decided = true;
|
|
return;
|
|
}
|
|
// Wait for a connection; the connection listener runs the check again.
|
|
if (!widget.connected()) return;
|
|
final empty = await serverHasNoWorkYet(widget.gateway);
|
|
if (!_active) return;
|
|
// Unreadable: stay open so the next connection retries the check.
|
|
if (empty == null) return;
|
|
_decided = true;
|
|
if (!empty) return;
|
|
await widget.store.markOffered(widget.serverScope);
|
|
await _showIfActive();
|
|
}
|
|
|
|
Future<void> _showIfActive() async {
|
|
if (!_active) return;
|
|
await _show();
|
|
}
|
|
|
|
Future<void> _show() async {
|
|
await showFirstRunWalkthrough(context, onClosed: widget.store.markSeen);
|
|
}
|
|
|
|
@override
|
|
Widget build(BuildContext context) => widget.child;
|
|
}
|