feat(app): open a pipeline stage from its URL

The route `/pipelines/:id[/:version]/stage/:key` now opens the pipeline
detail's Graph tab with the named stage selected and its authored
definition pane for the pinned version. A key the pinned definition does
not declare opens the Graph tab with nothing selected and no pane; no key
keeps the ordinary Summary tab.

The request is scoped to the pipeline and version the URL names, consumed
once the named pin's first reply is shown, and never replayed by a re-read,
a later version switch or a different pipeline. A route change from a pin
to latest re-reads latest, matching the web's requested-version rule.
This commit is contained in:
2026-10-22 11:42:11 +01:00
parent fc573e8743
commit eb16a4caba
7 changed files with 885 additions and 24 deletions
+1
View File
@@ -212,6 +212,7 @@ class _PipelinesAppState extends State<PipelinesApp> {
onRunStarted: _runStarted,
initialPipelineId: route.pipelineId,
initialVersion: route.version,
initialStageKey: route.stageKey,
),
AppDestination.runs: (_) => RunsDestination(
session: _session,
@@ -21,6 +21,7 @@ class PipelinesDestination extends StatelessWidget {
this.onRunStarted,
this.initialPipelineId,
this.initialVersion = 0,
this.initialStageKey,
});
final AppSession session;
@@ -38,6 +39,9 @@ class PipelinesDestination extends StatelessWidget {
final int? initialPipelineId;
final int initialVersion;
/// The definition stage a deep link names, or null for no stage request.
final String? initialStageKey;
@override
Widget build(BuildContext context) => AnimatedBuilder(
animation: session,
@@ -75,6 +79,7 @@ class PipelinesDestination extends StatelessWidget {
onRunStarted: onRunStarted,
initialPipelineId: initialPipelineId,
initialVersion: initialVersion,
initialStageKey: initialStageKey,
// A reconnect or an accepted template create both advance this counter;
// either change re-reads through the mounted controller.
syncToken: session.connectionEpoch + refreshToken,
+70 -4
View File
@@ -2,6 +2,7 @@ import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import '../../core/api_gateway.dart';
import 'pipeline_models.dart';
import 'pipeline_repository.dart';
import 'pipelines_controller.dart';
import 'widgets/pipeline_controls.dart';
@@ -29,6 +30,7 @@ class PipelinesScreen extends StatefulWidget {
this.onRunStarted,
this.initialPipelineId,
this.initialVersion = 0,
this.initialStageKey,
});
final ApiGateway gateway;
@@ -50,6 +52,13 @@ class PipelinesScreen extends StatefulWidget {
/// The pinned version for [initialPipelineId]; 0 means latest.
final int initialVersion;
/// The definition stage the route names for [initialPipelineId], or null.
///
/// The detail opens its Graph tab with this stage selected and its definition
/// pane; a key the pinned version does not declare opens the Graph tab with
/// nothing selected. Null keeps the ordinary default tab.
final String? initialStageKey;
@override
State<PipelinesScreen> createState() => _PipelinesScreenState();
}
@@ -57,6 +66,16 @@ class PipelinesScreen extends StatefulWidget {
class _PipelinesScreenState extends State<PipelinesScreen> {
late PipelinesController _controller;
/// Counts route stage requests so a re-read detail cannot replay an old one.
int _stageRequest = 0;
/// Whether the route's stage request has been handed to its named pin.
///
/// The screen, not the detail panel, owns this because the narrow layout
/// destroys the panel when it returns to the list: a deep link is a one-shot
/// intent, so coming back to the same pipeline later keeps the ordinary tab.
bool _stageRequestDone = false;
@override
void initState() {
super.initState();
@@ -81,12 +100,15 @@ class _PipelinesScreenState extends State<PipelinesScreen> {
// selected pipeline and requested version survive the reconnect.
_controller.load();
} else if (oldWidget.initialPipelineId != widget.initialPipelineId ||
oldWidget.initialVersion != widget.initialVersion) {
oldWidget.initialVersion != widget.initialVersion ||
oldWidget.initialStageKey != widget.initialStageKey) {
_stageRequest++;
_stageRequestDone = false;
final id = widget.initialPipelineId;
if (id != null) {
_controller.openPipeline(id, version: widget.initialVersion);
} else {
if (id == null) {
_controller.clearSelection();
} else if (!_isRoutePin(_controller.detail)) {
_controller.openPipeline(id, version: widget.initialVersion);
}
}
}
@@ -97,11 +119,47 @@ class _PipelinesScreenState extends State<PipelinesScreen> {
super.dispose();
}
/// Whether [detail] is the pipeline and pin the route names.
///
/// The shown detail must have been *requested* for the route's version, not
/// merely have resolved to it: a latest route (`initialVersion == 0`) never
/// matches a detail still displayed from a pinned request, so a route change
/// from a pin to latest re-reads latest. The web compares its requested
/// version the same way. A pinned route additionally requires the reply's own
/// concrete version.
bool _isRoutePin(PipelineDetail? detail) {
final id = widget.initialPipelineId;
if (detail == null || id == null || detail.id != id) return false;
final version = widget.initialVersion;
if (_controller.selectedVersion != version) return false;
return version <= 0 || detail.resolvedVersion == version;
}
/// The route's stage request while it is still pending, or null once spent.
///
/// The request names one stage of one pinned pipeline. It is handed to the
/// detail only until that pin's reply has been shown: the screen consumes the
/// request as soon as the first reply for the current selection arrives, so a
/// spent deep link cannot replay its pane when the operator later returns to
/// the same pipeline. The panel still scopes the request to its named
/// pipeline and version, which is what keeps it off an unrelated detail.
String? _takeStageKey() {
final key = widget.initialStageKey;
final target = widget.initialPipelineId;
if (key == null || key.isEmpty || target == null) return null;
if (_stageRequestDone) return null;
final detail = _controller.detail;
if (detail == null) return key;
_stageRequestDone = true;
return _isRoutePin(detail) ? key : null;
}
@override
Widget build(BuildContext context) {
return AnimatedBuilder(
animation: _controller,
builder: (context, _) {
final stageKey = _takeStageKey();
final body = LayoutBuilder(
builder: (context, constraints) {
final wide = constraints.maxWidth >= kPipelinesWideBreakpoint;
@@ -112,6 +170,10 @@ class _PipelinesScreenState extends State<PipelinesScreen> {
gateway: widget.gateway,
showBack: true,
onRunStarted: widget.onRunStarted,
stageKey: stageKey,
stagePipelineId: widget.initialPipelineId,
stageVersion: widget.initialVersion,
stageRequest: _stageRequest,
)
: PipelineListPanel(controller: _controller);
}
@@ -130,6 +192,10 @@ class _PipelinesScreenState extends State<PipelinesScreen> {
gateway: widget.gateway,
showBack: false,
onRunStarted: widget.onRunStarted,
stageKey: stageKey,
stagePipelineId: widget.initialPipelineId,
stageVersion: widget.initialVersion,
stageRequest: _stageRequest,
),
),
],
@@ -3,6 +3,7 @@ import 'dart:math' as math;
import 'package:flutter/material.dart';
import '../../../core/api_gateway.dart';
import '../../graph/domain/graph_definition.dart';
import '../../graph/widgets/stage_definition_view.dart';
import '../pipeline_models.dart';
import '../pipeline_query.dart';
@@ -30,7 +31,14 @@ class PipelineDetailPanel extends StatefulWidget {
required this.gateway,
required this.showBack,
this.onRunStarted,
});
this.stageKey,
this.stagePipelineId,
this.stageVersion = 0,
this.stageRequest = 0,
}) : assert(
stageKey == null || stagePipelineId != null,
'a routed stage names the pipeline it belongs to',
);
final PipelinesController controller;
final ApiGateway gateway;
@@ -39,6 +47,26 @@ class PipelineDetailPanel extends StatefulWidget {
/// A run started from this detail's Run action; receives the server's id.
final ValueChanged<int>? onRunStarted;
/// The stage the route names for this detail, or null when it names none.
final String? stageKey;
/// The pipeline [stageKey] belongs to; the request never applies to another.
final int? stagePipelineId;
/// The version [stageKey] was named for; 0 asks for latest.
///
/// The request applies only to a detail requested for this version, so a
/// later version switch on this screen cannot reopen it against a different
/// definition, and a latest request never inherits a pinned reply.
final int stageVersion;
/// Identifies one route stage request; 0 is the initial mount.
///
/// A different pipeline, version or key advances it, so one request opens one
/// definition pane even though the pinned detail may be re-read in place. A
/// later version switch from this screen is not a new route request.
final int stageRequest;
@override
State<PipelineDetailPanel> createState() => _PipelineDetailPanelState();
}
@@ -55,6 +83,9 @@ class _PipelineDetailPanelState extends State<PipelineDetailPanel> {
/// version is a different definition, so its mark is cleared.
String? _graphPin;
/// The route stage request already applied, or -1 before the first detail.
int _appliedStageRequest = -1;
PipelinesController get _controller => widget.controller;
@override
@@ -62,6 +93,7 @@ class _PipelineDetailPanelState extends State<PipelineDetailPanel> {
final detail = _controller.detail;
if (detail == null) return _withoutDetail(context);
_retainGraphSelection(detail);
_applyStageRequest(context, detail);
return LayoutBuilder(
builder: (context, constraints) {
final headerLimit = _headerLimit(constraints);
@@ -149,6 +181,62 @@ class _PipelineDetailPanelState extends State<PipelineDetailPanel> {
_graphSelection = null;
}
/// Applies the route's stage request to the pinned [detail].
///
/// The request belongs to the pipeline and version the URL names, so a detail
/// for anything else is left alone: opening another pipeline must not inherit
/// a deep link the operator has navigated away from. Over the named pin, the
/// Graph tab opens for the requested key. A key the pinned definition
/// declares selects that node and opens its landed definition pane for the
/// pinned version; a key it does not declare opens the Graph tab with nothing
/// selected and no pane, so no stage is reconstructed. A reply without a
/// graph has nothing to declare, so it follows the same no-selection path.
void _applyStageRequest(BuildContext context, PipelineDetail detail) {
final stageKey = widget.stageKey;
if (stageKey == null || stageKey.isEmpty) return;
if (_appliedStageRequest == widget.stageRequest) return;
if (!_namesShownPin(detail)) return;
_appliedStageRequest = widget.stageRequest;
_tab = PipelineDetailTab.graph;
final graph = detail.graph;
final declared =
graph != null && graphNodes(graph).any((node) => node.key == stageKey);
_graphSelection = declared ? stageKey : null;
if (graph == null || !declared) return;
// A page cannot be pushed during build: open it after this frame, and only
// while this exact pinned reply is still the one shown.
WidgetsBinding.instance.addPostFrameCallback((_) {
if (!mounted || _appliedStageRequest != widget.stageRequest) return;
final shown = _controller.detail;
if (shown == null ||
shown.id != detail.id ||
shown.resolvedVersion != detail.resolvedVersion) {
return;
}
openStageDefinition(
context,
graph: graph,
stageKey: stageKey,
pipelineId: detail.id,
pipelineName: detail.name,
version: detail.resolvedVersion,
);
});
}
/// Whether [detail] is the pipeline and pin this route stage request names.
///
/// The shown detail must be the reply to the route's own request, so a
/// request for latest (`stageVersion == 0`) never applies to a detail still
/// displayed from a pinned request. A pinned request also requires the
/// reply's concrete version.
bool _namesShownPin(PipelineDetail detail) {
if (detail.id != widget.stagePipelineId) return false;
final version = widget.stageVersion;
if (_controller.selectedVersion != version) return false;
return version <= 0 || detail.resolvedVersion == version;
}
/// Selects a node and opens the landed definition page for the pinned graph.
void _openGraphStage(
BuildContext context,