feat(app): show recorded session export state in visit pane

This commit is contained in:
2026-10-22 03:26:33 +01:00
parent 559d767f39
commit ddd8eacb1f
3 changed files with 482 additions and 57 deletions
@@ -8,12 +8,15 @@ import '../../artifacts/domain/artifact_url.dart';
import '../../artifacts/ui/artifact_external_open.dart';
import 'run_detail_visit_session_state.dart';
/// The visit's recorded session pointer and, when the visit exported one, a
/// read-only external open of that document.
/// The visit's recorded session pointer, its recorded export state and, when
/// the visit exported one, a read-only external open of that document.
///
/// The state comes from [detailVisitSession], so a legacy `session.html`, a
/// repair, a still-running session and a failed one each report what the server
/// recorded. The open goes through the landed safe-link helper: the recorded url
/// recorded. Complete, partial, missing, skipped, repair and unrecognised
/// states each keep the server's own word and diagnostic; recorded repair
/// attempts and their open-option labels are shown read-only and make no
/// request. The open goes through the landed safe-link helper: the recorded url
/// is resolved by [resolveArtifactUrl] and passed to [openArtifactExternally]
/// without being fetched, rewritten or previewed. A refusal is reported.
class RunVisitSession extends StatefulWidget {
@@ -53,17 +56,34 @@ class _RunVisitSessionState extends State<RunVisitSession> {
? null
: resolveArtifactUrl(widget.configuredEndpoint, export.artifact.url);
final note = export?.statusNote;
final fact = session.exportFact;
final showReason =
export != null &&
fact?.reason != null &&
fact!.state != VisitSessionExportState.repair;
final children = <Widget>[
if (session.sessionId != null)
_SessionFact(label: 'Session', value: session.sessionId!),
if (export != null) ...[
if (note != null) Text(note),
if (resolved == null)
const Text(visitSessionEndpointMissing)
else
_openButton(export.artifact, resolved),
] else
Text(session.message),
if (fact != null)
_SessionFact(
key: const Key('run-visit-session-export'),
label: 'Export',
value: fact.word,
),
if (showReason)
_SessionFact(
key: const Key('run-visit-session-export-reason'),
label: 'Reason',
value: fact!.reason!,
),
if (export != null && note != null) Text(note),
..._repairFacts(session.repairs),
if (export == null)
Text(session.message)
else if (resolved == null)
const Text(visitSessionEndpointMissing)
else
_openButton(export.artifact, resolved),
if (_status != null)
Padding(
padding: const EdgeInsets.only(top: 8),
@@ -110,6 +130,33 @@ class _RunVisitSessionState extends State<RunVisitSession> {
);
}
/// Recorded repair attempts, in the pane's own fact rows. Nothing here is a
/// control: the repair request belongs to its own action and is not wired.
List<Widget> _repairFacts(List<VisitSessionRepair> repairs) {
final facts = <Widget>[];
for (var index = 0; index < repairs.length; index += 1) {
final repair = repairs[index];
facts.add(
_SessionFact(
key: ValueKey('run-visit-session-repair-$index'),
label: 'Repair',
value: repair.label,
),
);
final option = repair.option;
if (option != null) {
facts.add(
_SessionFact(
key: ValueKey('run-visit-session-repair-option-$index'),
label: 'Repair option',
value: option,
),
);
}
}
return facts;
}
List<Widget> _spaced(List<Widget> children) => [
for (var index = 0; index < children.length; index += 1) ...[
if (index > 0) const SizedBox(height: 8),
@@ -119,7 +166,7 @@ class _RunVisitSessionState extends State<RunVisitSession> {
}
class _SessionFact extends StatelessWidget {
const _SessionFact({required this.label, required this.value});
const _SessionFact({super.key, required this.label, required this.value});
final String label;
final String value;
@@ -3,9 +3,8 @@ import '../../artifacts/domain/artifact_record.dart';
import '../../artifacts/domain/artifact_selection.dart';
/// The exact wording for a visit that never started a harness session, in the
/// web audit pane's order: a skipped visit, a stopped one, a model visit whose
/// session is still being created, a failed one, and a model visit with no
/// identity at all. Only a non-model visit with nothing recorded gets the
/// web audit pane's order: skipped, stopped, being created, failed, and a model
/// visit with no identity. Only a non-model visit with nothing recorded gets the
/// generic sentence.
const String visitSessionSkipped =
'This visit was skipped; no harness session was started.';
@@ -21,6 +20,59 @@ const String visitSessionNone = 'This visit has no harness session.';
const String visitSessionEndpointMissing =
'Set the server URL in Settings to open the session.';
/// The export state the pane reports. A status this client does not know is
/// [unknown] and is shown verbatim; it is never rounded to complete.
enum VisitSessionExportState {
complete,
partial,
missing,
skipped,
repair,
unknown,
}
/// The one state line for a visit's recorded export, with the server's own
/// diagnostic as [reason] when it recorded one.
class VisitSessionExportFact {
const VisitSessionExportFact({
required this.state,
required this.word,
this.reason,
});
final VisitSessionExportState state;
/// The state word shown to the operator. An unknown status keeps the
/// server's exact word here instead of being mapped to a known state.
final String word;
/// The server-recorded diagnostic, verbatim, or null when there was none.
final String? reason;
}
/// One recorded repair attempt and the read-only labels the pane shows for it.
class VisitSessionRepair {
const VisitSessionRepair({
required this.status,
required this.messages,
this.diagnostic,
this.option,
});
final String status;
final int messages;
final String? diagnostic;
/// The web pane's open label, shown read-only, or null when this repair is
/// the document the main open action already points at.
final String? option;
/// The web audit pane's repair label, without its `Repair: ` prefix.
String get label =>
'$status · $messages messages.'
'${diagnostic == null ? '' : ' $diagnostic'}';
}
/// A recorded session export document and the evidence the server recorded for
/// it.
class VisitSessionExport {
@@ -28,60 +80,102 @@ class VisitSessionExport {
required this.artifact,
this.status,
this.diagnostic,
this.messages = 0,
this.htmlBytes = 0,
this.truncated = false,
this.repaired = false,
});
final ArtifactRecord artifact;
final String? status;
final String? diagnostic;
final int messages;
final int htmlBytes;
final bool truncated;
/// A partial or failed export is still the recorded document; it stays
/// openable and the pane says what the evidence reports.
bool get isComplete => status == 'complete' && !truncated;
/// True when the document is one of the visit's recorded repair attempts.
final bool repaired;
/// The evidence sentence shown beside a present but incomplete export, or
/// null when the export is complete or the visit recorded no evidence.
/// Completeness needs the server's complete status plus positive message and
/// byte counts, an untruncated document and no diagnostic. An absent or
/// partial record is never promoted to complete.
bool get isComplete =>
status == 'complete' &&
messages > 0 &&
htmlBytes > 0 &&
!truncated &&
diagnostic == null;
/// The evidence sentence beside a present but incomplete export, or null
/// when the export is complete or no evidence was recorded.
String? get statusNote {
if (isComplete) return null;
if (status == null && !truncated) return null;
return 'This export is ${status ?? 'partial'}; full session evidence is '
'not available.';
if (status == null && messages <= 0 && !truncated) return null;
final word = status == null || status == 'complete' ? 'partial' : status;
return 'This export is $word; full session evidence is not available.';
}
}
/// A visit's recorded session: its identity, an openable export document and,
/// when neither exists, the one sentence describing the recorded state.
/// A visit's recorded session: identity, openable export, recorded export
/// state, recorded repairs and, without a document, the recorded sentence.
class VisitSessionState {
const VisitSessionState({this.sessionId, this.export, this.message = ''});
const VisitSessionState({
this.sessionId,
this.export,
this.message = '',
this.exportFact,
this.repairs = const [],
});
final String? sessionId;
final VisitSessionExport? export;
/// Empty exactly when [export] is present.
final String message;
/// Null when the visit recorded no session at all.
final VisitSessionExportFact? exportFact;
/// Every recorded repair attempt, oldest first, read-only.
final List<VisitSessionRepair> repairs;
}
/// Resolves the recorded session state without inventing a session.
///
/// The export is looked up through the recorded export evidence (including a
/// repair that replaced it) and then, for a historical visit that recorded no
/// evidence at all, through the `session.html` its inventory carries. When the
/// evidence names no file, its own status and diagnostic are reported instead
/// of claiming the inventory is empty.
/// repair that replaced it) and then, for a historical visit with no evidence,
/// through its `session.html`. When the evidence names no file, its own status
/// and diagnostic are reported instead of claiming the inventory is empty.
VisitSessionState detailVisitSession(JsonMap step) {
final sessionId = detailVisitSessionIdentity(step);
final export = detailVisitSessionExport(step);
final repairs = _repairs(step, export);
if (export != null) {
return VisitSessionState(sessionId: sessionId, export: export);
return VisitSessionState(
sessionId: sessionId,
export: export,
exportFact: _exportFact(export),
repairs: repairs,
);
}
if (sessionId != null) {
return VisitSessionState(
sessionId: sessionId,
message: _missingExportMessage(step, sessionId),
exportFact: _missingFact(step),
repairs: repairs,
);
}
return VisitSessionState(message: _noSessionMessage(step));
return VisitSessionState(
message: _noSessionMessage(step),
exportFact: _isSkipped(step)
? const VisitSessionExportFact(
state: VisitSessionExportState.skipped,
word: 'skipped',
)
: null,
repairs: repairs,
);
}
/// The recorded harness session identity, from the step or its export evidence.
@@ -96,19 +190,21 @@ String? detailVisitSessionIdentity(JsonMap step) {
/// is present in the inventory.
///
/// The step's own `session_export` is preferred; a repair document is used
/// when that is the file the inventory actually carries. A visit with no export
/// evidence at all falls back to its `session.html` system artifact, exactly as
/// the web audit pane does for runs recorded before the evidence field existed.
/// when that is the file the inventory carries. A visit with no export evidence
/// falls back to its `session.html`, exactly as the web audit pane does.
VisitSessionExport? detailVisitSessionExport(JsonMap step) {
final evidence = _exportEvidence(step);
for (final entry in evidence) {
final artifact = _artifactNamed(step, _text(entry['html']));
final artifact = _artifactNamed(step, _text(entry.evidence['html']));
if (artifact == null) continue;
return VisitSessionExport(
artifact: artifact,
status: _text(entry['status']),
diagnostic: _text(entry['diagnostic']),
truncated: entry['truncated'] == true,
status: _text(entry.evidence['status']),
diagnostic: _text(entry.evidence['diagnostic']),
messages: _count(entry.evidence['messages']),
htmlBytes: _count(entry.evidence['html_bytes']),
truncated: entry.evidence['truncated'] == true,
repaired: entry.repaired,
);
}
if (evidence.isNotEmpty) return null;
@@ -120,6 +216,99 @@ VisitSessionExport? detailVisitSessionExport(JsonMap step) {
return null;
}
VisitSessionExportFact _exportFact(VisitSessionExport export) {
if (export.repaired) {
return VisitSessionExportFact(
state: VisitSessionExportState.repair,
word: 'repair',
reason: export.diagnostic,
);
}
final status = export.status;
if (status == 'complete') {
if (export.isComplete) {
return const VisitSessionExportFact(
state: VisitSessionExportState.complete,
word: 'complete',
);
}
return _partialFact(export);
}
if (status == null) {
return VisitSessionExportFact(
state: VisitSessionExportState.unknown,
word: 'unknown',
reason: export.diagnostic,
);
}
if (_partialStatuses.contains(status)) return _partialFact(export);
return VisitSessionExportFact(
state: VisitSessionExportState.unknown,
word: status,
reason: export.diagnostic,
);
}
VisitSessionExportFact _partialFact(VisitSessionExport export) =>
VisitSessionExportFact(
state: VisitSessionExportState.partial,
word: 'partial',
reason: export.diagnostic,
);
VisitSessionExportFact _missingFact(JsonMap step) {
final evidence = _firstEvidence(step);
final status = evidence == null ? null : _text(evidence['status']);
final diagnostic = evidence == null ? null : _text(evidence['diagnostic']);
if (status != null &&
status != 'complete' &&
!_partialStatuses.contains(status)) {
return VisitSessionExportFact(
state: VisitSessionExportState.unknown,
word: status,
reason: diagnostic,
);
}
return VisitSessionExportFact(
state: VisitSessionExportState.missing,
word: 'missing',
reason: diagnostic,
);
}
const Set<String> _partialStatuses = <String>{
'partial',
'empty',
'failed',
'truncated',
'incomplete',
'unavailable',
};
List<VisitSessionRepair> _repairs(JsonMap step, VisitSessionExport? export) {
final recorded = step['session_export_repairs'];
if (recorded is! List) return const [];
final selectedName = export?.artifact.name;
final repairs = <VisitSessionRepair>[];
for (final entry in recorded) {
if (entry is! Map) continue;
final artifact = _artifactNamed(step, _text(entry['html']));
final selected = artifact != null && artifact.name == selectedName;
repairs.add(
VisitSessionRepair(
status: _text(entry['status']) ?? 'partial',
messages: _count(entry['messages']),
diagnostic: _text(entry['diagnostic']),
option: artifact == null || selected ? null : 'Open repaired export',
),
);
}
return repairs;
}
bool _isSkipped(JsonMap step) =>
_text(step['status']) == 'skipped' || _text(step['outcome']) == 'skipped';
String _missingExportMessage(JsonMap step, String sessionId) {
final evidence = _firstEvidence(step);
final recovery = step['session_export_recovery'];
@@ -140,9 +329,7 @@ String _missingExportMessage(JsonMap step, String sessionId) {
String _noSessionMessage(JsonMap step) {
final status = _text(step['status']);
if (status == 'skipped' || _text(step['outcome']) == 'skipped') {
return visitSessionSkipped;
}
if (_isSkipped(step)) return visitSessionSkipped;
if (status == 'canceled' || status == 'interrupted') {
return visitSessionStopped;
}
@@ -162,7 +349,7 @@ String _noSessionMessage(JsonMap step) {
/// complete original, then every remaining candidate. A failed later attempt
/// never hides an earlier verified document; an older original never hides the
/// repair that replaced it.
List<Map> _exportEvidence(JsonMap step) {
List<_RecordedExport> _exportEvidence(JsonMap step) {
final repairs = <Map>[];
final recordedRepairs = step['session_export_repairs'];
if (recordedRepairs is List) {
@@ -171,25 +358,32 @@ List<Map> _exportEvidence(JsonMap step) {
}
}
final original = step['session_export'];
final ordered = <Map>[];
void add(Map entry) {
final ordered = <_RecordedExport>[];
void add(Map entry, bool repaired) {
for (final candidate in ordered) {
if (identical(candidate, entry)) return;
if (identical(candidate.evidence, entry)) return;
}
ordered.add(entry);
ordered.add(_RecordedExport(entry, repaired));
}
for (final repair in repairs) {
if (_isComplete(repair)) add(repair);
if (_isComplete(repair)) add(repair, true);
}
if (original is Map && _isComplete(original)) add(original);
if (original is Map && _isComplete(original)) add(original, false);
for (final repair in repairs) {
add(repair);
add(repair, true);
}
if (original is Map) add(original);
if (original is Map) add(original, false);
return ordered;
}
class _RecordedExport {
const _RecordedExport(this.evidence, this.repaired);
final Map evidence;
final bool repaired;
}
Map? _firstEvidence(JsonMap step) {
final original = step['session_export'];
if (original is Map) return original;
@@ -204,15 +398,14 @@ Map? _firstEvidence(JsonMap step) {
bool _isComplete(Map evidence) =>
_text(evidence['status']) == 'complete' &&
_positive(evidence['messages']) &&
_positive(evidence['html_bytes']) &&
_count(evidence['messages']) > 0 &&
_count(evidence['html_bytes']) > 0 &&
evidence['truncated'] != true &&
_text(evidence['diagnostic']) == null;
bool _positive(dynamic value) {
if (value is num) return value > 0;
if (value is String) return (int.tryParse(value.trim()) ?? 0) > 0;
return false;
int _count(dynamic value) {
if (value is num) return value.toInt();
return int.tryParse('${value ?? ''}'.trim()) ?? 0;
}
ArtifactRecord? _artifactNamed(JsonMap step, String? name) {
@@ -0,0 +1,185 @@
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/core/api_gateway.dart';
import 'package:pipelines_app/features/runs/ui/run_detail_visit_session.dart';
import 'package:pipelines_app/features/runs/ui/run_detail_visit_session_state.dart';
import 'run_detail_visit_support.dart';
Future<void> pumpSessionExport(WidgetTester tester, JsonMap step) =>
tester.pumpWidget(
MaterialApp(
home: Scaffold(
body: RunVisitSession(
step: step,
configuredEndpoint: 'ws://example.test/connect',
),
),
),
);
JsonMap sessionStep() => firstVisitStep(visitRunFixture());
JsonMap artifact(String name) => <String, dynamic>{
'name': name,
'url': 'https://example.test/artifacts/$name',
'content_type': 'text/html',
'size_bytes': 100,
};
void main() {
testWidgets('a verified export reports complete', (tester) async {
await pumpSessionExport(tester, sessionStep());
expect(find.text('complete'), findsOneWidget);
expect(find.text('partial'), findsNothing);
expect(find.textContaining('full session evidence'), findsNothing);
expect(find.text('Reason'), findsNothing);
});
testWidgets('a partial export keeps the server status and its reason', (
tester,
) async {
final step = sessionStep();
step['session_export'] = <String, dynamic>{
'html': 'session.html',
'status': 'failed',
'messages': 2,
'diagnostic': 'The native read was refused.',
};
await pumpSessionExport(tester, step);
expect(find.text('partial'), findsOneWidget);
expect(
find.textContaining(
'This export is failed; full session evidence is not available.',
),
findsOneWidget,
);
expect(find.text('The native read was refused.'), findsOneWidget);
});
testWidgets('complete status without evidence is not promoted to complete', (
tester,
) async {
final step = sessionStep();
step['session_export'] = <String, dynamic>{
'html': 'session.html',
'status': 'complete',
'messages': 0,
'html_bytes': 0,
'diagnostic': 'Bounded read returned no messages.',
};
await pumpSessionExport(tester, step);
expect(find.text('complete'), findsNothing);
expect(find.text('partial'), findsOneWidget);
expect(find.text('Bounded read returned no messages.'), findsOneWidget);
});
testWidgets('an export with no recorded evidence stays unknown', (
tester,
) async {
final step = sessionStep()..remove('session_export');
await pumpSessionExport(tester, step);
expect(find.text('unknown'), findsOneWidget);
expect(find.text('complete'), findsNothing);
});
testWidgets('a missing export reports missing and the server reason', (
tester,
) async {
final step = sessionStep();
step['session_export'] = <String, dynamic>{
'html': 'session.html',
'status': 'failed',
'diagnostic': 'The export file was not listed.',
};
step['artifacts'] = <dynamic>[artifact('plan.csv')];
await pumpSessionExport(tester, step);
expect(find.text('missing'), findsOneWidget);
expect(
find.textContaining('The export file was not listed.'),
findsOneWidget,
);
expect(find.textContaining('Open '), findsNothing);
});
testWidgets('a skipped visit reports skipped and its recorded sentence', (
tester,
) async {
final step = sessionStep();
step['status'] = 'skipped';
step['outcome'] = 'skipped';
step
..remove('session_id')
..remove('session_export')
..remove('artifacts');
await pumpSessionExport(tester, step);
expect(find.text('skipped'), findsOneWidget);
expect(find.text(visitSessionSkipped), findsOneWidget);
});
testWidgets('recorded repairs and their open labels stay read-only', (
tester,
) async {
final step = sessionStep();
step['session_export'] = <String, dynamic>{
'html': 'session.html',
'status': 'failed',
'messages': 0,
'diagnostic': 'The first export failed.',
};
step['session_export_repairs'] = <dynamic>[
<String, dynamic>{
'html': 'session-repair-1.html',
'status': 'failed',
'messages': 0,
'diagnostic': 'The first repair failed.',
},
<String, dynamic>{
'html': 'session-repair-2.html',
'status': 'complete',
'messages': 3,
'html_bytes': 500,
},
];
step['artifacts'] = <dynamic>[
artifact('plan.csv'),
artifact('session.html'),
artifact('session-repair-1.html'),
artifact('session-repair-2.html'),
];
await pumpSessionExport(tester, step);
expect(find.text('repair'), findsOneWidget);
expect(
find.text('failed · 0 messages. The first repair failed.'),
findsOneWidget,
);
expect(find.text('complete · 3 messages.'), findsOneWidget);
expect(find.text('Open repaired export'), findsOneWidget);
expect(
find.widgetWithText(TextButton, 'Open repaired export'),
findsNothing,
);
expect(find.text('Open session-repair-2.html'), findsOneWidget);
});
testWidgets('an unrecognised export status is kept verbatim', (tester) async {
final step = sessionStep();
step['session_export'] = <String, dynamic>{
'html': 'session.html',
'status': 'quarantined',
'diagnostic': 'The server quarantined this export.',
};
await pumpSessionExport(tester, step);
expect(find.text('quarantined'), findsOneWidget);
expect(find.text('complete'), findsNothing);
expect(find.text('The server quarantined this export.'), findsOneWidget);
});
}