Files
pipelines/app/lib/features/walkthrough/walkthrough_store.dart
T
alan 30ba70ade8 Add first-run walkthrough
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.
2026-11-12 02:23:15 +00:00

119 lines
3.6 KiB
Dart

import 'package:shared_preferences/shared_preferences.dart';
/// The device-level key for "the first-run walkthrough was finished or skipped".
/// It is per device, not per server, so a new server never repeats it.
const String walkthroughSeenKey = 'pipelines.next.firstRunWalkthrough.v1';
/// The key listing the server scopes that were already offered the walkthrough
/// because they had no pipelines, runs or chats yet.
const String walkthroughOfferedKey = 'pipelines.next.walkthroughOffered.v1';
/// The persistence seam for the walkthrough. A store that cannot be read or
/// written reports "seen" and "offered", so an unavailable store never nags.
abstract interface class WalkthroughStore {
Future<bool> isSeen();
Future<void> markSeen();
Future<bool> wasOffered(String serverScope);
Future<void> markOffered(String serverScope);
}
Future<SharedPreferences?> _openPreferences() async {
try {
return await SharedPreferences.getInstance();
} catch (_) {
return null;
}
}
/// `shared_preferences`-backed storage under the `pipelines.next` keys.
///
/// [open] is the seam for an unavailable platform store (tests pass one that
/// yields null); production opens the real preferences.
class SharedPreferencesWalkthroughStore implements WalkthroughStore {
const SharedPreferencesWalkthroughStore({this.open = _openPreferences});
final Future<SharedPreferences?> Function() open;
Future<SharedPreferences?> _preferences() => open();
@override
Future<bool> isSeen() async {
final preferences = await _preferences();
if (preferences == null) return true;
try {
return preferences.getBool(walkthroughSeenKey) ?? false;
} catch (_) {
return true;
}
}
@override
Future<void> markSeen() async {
final preferences = await _preferences();
if (preferences == null) return;
try {
await preferences.setBool(walkthroughSeenKey, true);
} catch (_) {
// Nothing to report: the walkthrough is still dismissed for this run.
}
}
@override
Future<bool> wasOffered(String serverScope) async {
final preferences = await _preferences();
if (preferences == null) return true;
try {
final offered = preferences.getStringList(walkthroughOfferedKey);
return offered?.contains(serverScope) ?? false;
} catch (_) {
return true;
}
}
@override
Future<void> markOffered(String serverScope) async {
final preferences = await _preferences();
if (preferences == null) return;
try {
final offered = <String>{
...?preferences.getStringList(walkthroughOfferedKey),
serverScope,
};
await preferences.setStringList(walkthroughOfferedKey, offered.toList());
} catch (_) {
// A failed write only means the offer may show again later.
}
}
}
/// An in-memory store for tests and previews. It never touches the platform
/// store, so a fixture cannot mark a real device as seen.
class MemoryWalkthroughStore implements WalkthroughStore {
MemoryWalkthroughStore({this.seen = false, Set<String>? offered})
: _offered = {...?offered};
/// Whether the walkthrough is marked seen.
bool seen;
final Set<String> _offered;
/// The server scopes already offered the walkthrough.
Set<String> get offered => Set.unmodifiable(_offered);
@override
Future<bool> isSeen() async => seen;
@override
Future<void> markSeen() async => seen = true;
@override
Future<bool> wasOffered(String serverScope) async =>
_offered.contains(serverScope);
@override
Future<void> markOffered(String serverScope) async =>
_offered.add(serverScope);
}