fai/chain-studio
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

fix(docs): page help buttons open the right topic + wiring guard

Browse source 
The Federation and Runs help buttons opened the architecture doc:
federation.md/runs.md existed as assets but had no _DocEntry, so
showFaiDoc resolved the unknown slug to _kDocs.first. Register both
(onWelcome: false, so they don't clutter the newcomer grid but are
reachable), split the Welcome grid onto the curated subset, and make
the unknown-slug fallback assert in debug instead of silently opening
the wrong topic.

Guard (no-bugfix-without-a-guard): doc_help_wiring_test.dart scans
lib/ for every showFaiDoc('slug') call and asserts each has a
registered entry AND both assets/docs/<slug>[_de].md files. Exposes
kKnownDocSlugs for the test.

Signed-off-by: flemming-it <stefan.a.flemming@googlemail.com>
This commit is contained in:
flemming-it 2026-07-20 02:00:56 +02:00
parent 588f437395
commit 5a3f00bb2c
7 changed files with 226 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

7
lib/l10n/app_de.arb
View file

@ -50,6 +50,10 @@
"welcomeDocFlowsBlurb": "YAML-Grundlagen, Templating-Referenz, das Extract→Summarize-Beispiel.",
"welcomeDocApprovalsTitle": "Freigaben",
"welcomeDocApprovalsBlurb": "Human-in-the-Loop-Checkpoints — wann nutzen, wie das Audit-Log sie protokolliert.",
"welcomeDocFederationTitle": "Föderation",
"welcomeDocFederationBlurb": "Weitere Hubs (Satelliten) anbinden, damit ihre Fähigkeiten hier nutzbar werden — was ein Satellit ist und wie die Anbindung abläuft.",
"welcomeDocRunsTitle": "Hintergrund-Läufe",
"welcomeDocRunsBlurb": "Flows, die im Hintergrund weiterlaufen — wozu, wie man die Funktion einschaltet und die Läufe überwacht.",
"helpTooltip": "Hilfe",
"errApprovalRejected": "Freigabe vom Reviewer abgelehnt.",
"errApprovalRejectedHint": "Der Reviewer hat den Step abgelehnt. Begründung steht im Audit-Log.",
@ -104,6 +108,7 @@
"sidebarSettingsTooltip": "Einstellungen (⌘;)",
"sidebarChannelTooltip": "Aktiver Kanal — klicken zum Wechseln.\nproduction = stabil · beta = Vorabversion · dev = laufend · local = Arbeitsumgebung",
"buttonCancel": "Abbrechen",
"buttonLearnMore": "Mehr erfahren",
"buttonSave": "Speichern",
"buttonClose": "Schließen",
"buttonRetry": "Erneut versuchen",
@ -1764,6 +1769,8 @@
"federationCapabilities": "{count} angebotene Fähigkeiten",
"federationAddDialogTitle": "Registrierungs-Token ausstellen",
"federationNameLabel": "Satelliten-Name",
"federationAddIntro": "Ein Satellit ist ein weiterer Hub, den dieser Hub anbindet — dessen Fähigkeiten werden dann hier in Flows nutzbar. Sie vergeben einen Namen und erhalten ein einmaliges Token, mit dem sich der Satellit bei diesem Hub anmeldet.",
"federationNameHelp": "Frei wählbarer Name, um diesen Satelliten in der Liste wiederzuerkennen (z. B. Standort oder Zweck). Rein zur Anzeige — ändert nichts an der Technik.",
"federationIssueButton": "Ausstellen",
"federationIssueFailed": "Token konnte nicht ausgestellt werden: {error}",
"federationEnrollmentTitle": "{name} einrichten",

7
lib/l10n/app_en.arb
View file

@ -58,6 +58,10 @@
"welcomeDocFlowsBlurb": "YAML basics, templating reference, the extract→summarize example.",
"welcomeDocApprovalsTitle": "Approvals",
"welcomeDocApprovalsBlurb": "Human-in-the-loop checkpoints — when to use them, how the audit log records them.",
"welcomeDocFederationTitle": "Federation",
"welcomeDocFederationBlurb": "Connect other hubs (satellites) so their capabilities become usable here — what a satellite is and how enrolment works.",
"welcomeDocRunsTitle": "Background runs",
"welcomeDocRunsBlurb": "Flows that keep working in the background — what they are for, how to switch the feature on and monitor the runs.",
"helpTooltip": "Help",
"errApprovalRejected": "Approval rejected by reviewer.",
"errApprovalRejectedHint": "The reviewer marked this step as rejected. Check the audit log for the reviewer's reason.",
@ -112,6 +116,7 @@
"sidebarSettingsTooltip": "Settings (⌘;)",
"sidebarChannelTooltip": "Active channel — click to switch.\nproduction = stable · beta = pre-release · dev = rolling · local = workspace",
"buttonCancel": "Cancel",
"buttonLearnMore": "Learn more",
"buttonSave": "Save",
"buttonClose": "Close",
"buttonRetry": "Retry",
@ -1793,6 +1798,8 @@
},
"federationAddDialogTitle": "Issue an enrollment token",
"federationNameLabel": "Satellite name",
"federationAddIntro": "A satellite is another hub this hub connects to — its capabilities then become usable here in flows. You give it a name and receive a one-time token the satellite uses to enrol with this hub.",
"federationNameHelp": "A free-form name to recognize this satellite in the list (e.g. its location or purpose). Display only — it changes nothing technical.",
"federationIssueButton": "Issue",
"federationIssueFailed": "Could not issue token: {error}",
"@federationIssueFailed": {

42
lib/l10n/app_localizations.dart
View file

@ -398,6 +398,30 @@ abstract class AppLocalizations {
/// **'Human-in-the-loop checkpoints — when to use them, how the audit log records them.'**
String get welcomeDocApprovalsBlurb;
/// No description provided for @welcomeDocFederationTitle.
///
/// In en, this message translates to:
/// **'Federation'**
String get welcomeDocFederationTitle;
/// No description provided for @welcomeDocFederationBlurb.
///
/// In en, this message translates to:
/// **'Connect other hubs (satellites) so their capabilities become usable here — what a satellite is and how enrolment works.'**
String get welcomeDocFederationBlurb;
/// No description provided for @welcomeDocRunsTitle.
///
/// In en, this message translates to:
/// **'Background runs'**
String get welcomeDocRunsTitle;
/// No description provided for @welcomeDocRunsBlurb.
///
/// In en, this message translates to:
/// **'Flows that keep working in the background — what they are for, how to switch the feature on and monitor the runs.'**
String get welcomeDocRunsBlurb;
/// No description provided for @helpTooltip.
///
/// In en, this message translates to:
@ -680,6 +704,12 @@ abstract class AppLocalizations {
/// **'Cancel'**
String get buttonCancel;
/// No description provided for @buttonLearnMore.
///
/// In en, this message translates to:
/// **'Learn more'**
String get buttonLearnMore;
/// No description provided for @buttonSave.
///
/// In en, this message translates to:
@ -5347,6 +5377,18 @@ abstract class AppLocalizations {
/// **'Satellite name'**
String get federationNameLabel;
/// No description provided for @federationAddIntro.
///
/// In en, this message translates to:
/// **'A satellite is another hub this hub connects to — its capabilities then become usable here in flows. You give it a name and receive a one-time token the satellite uses to enrol with this hub.'**
String get federationAddIntro;
/// No description provided for @federationNameHelp.
///
/// In en, this message translates to:
/// **'A free-form name to recognize this satellite in the list (e.g. its location or purpose). Display only — it changes nothing technical.'**
String get federationNameHelp;
/// No description provided for @federationIssueButton.
///
/// In en, this message translates to:

25
lib/l10n/app_localizations_de.dart
View file

@ -180,6 +180,20 @@ class AppLocalizationsDe extends AppLocalizations {
String get welcomeDocApprovalsBlurb =>
'Human-in-the-Loop-Checkpoints — wann nutzen, wie das Audit-Log sie protokolliert.';
@override
String get welcomeDocFederationTitle => 'Föderation';
@override
String get welcomeDocFederationBlurb =>
'Weitere Hubs (Satelliten) anbinden, damit ihre Fähigkeiten hier nutzbar werden — was ein Satellit ist und wie die Anbindung abläuft.';
@override
String get welcomeDocRunsTitle => 'Hintergrund-Läufe';
@override
String get welcomeDocRunsBlurb =>
'Flows, die im Hintergrund weiterlaufen — wozu, wie man die Funktion einschaltet und die Läufe überwacht.';
@override
String get helpTooltip => 'Hilfe';
@ -338,6 +352,9 @@ class AppLocalizationsDe extends AppLocalizations {
@override
String get buttonCancel => 'Abbrechen';
@override
String get buttonLearnMore => 'Mehr erfahren';
@override
String get buttonSave => 'Speichern';
@ -3164,6 +3181,14 @@ class AppLocalizationsDe extends AppLocalizations {
@override
String get federationNameLabel => 'Satelliten-Name';
@override
String get federationAddIntro =>
'Ein Satellit ist ein weiterer Hub, den dieser Hub anbindet — dessen Fähigkeiten werden dann hier in Flows nutzbar. Sie vergeben einen Namen und erhalten ein einmaliges Token, mit dem sich der Satellit bei diesem Hub anmeldet.';
@override
String get federationNameHelp =>
'Frei wählbarer Name, um diesen Satelliten in der Liste wiederzuerkennen (z. B. Standort oder Zweck). Rein zur Anzeige — ändert nichts an der Technik.';
@override
String get federationIssueButton => 'Ausstellen';

25
lib/l10n/app_localizations_en.dart
View file

@ -181,6 +181,20 @@ class AppLocalizationsEn extends AppLocalizations {
String get welcomeDocApprovalsBlurb =>
'Human-in-the-loop checkpoints — when to use them, how the audit log records them.';
@override
String get welcomeDocFederationTitle => 'Federation';
@override
String get welcomeDocFederationBlurb =>
'Connect other hubs (satellites) so their capabilities become usable here — what a satellite is and how enrolment works.';
@override
String get welcomeDocRunsTitle => 'Background runs';
@override
String get welcomeDocRunsBlurb =>
'Flows that keep working in the background — what they are for, how to switch the feature on and monitor the runs.';
@override
String get helpTooltip => 'Help';
@ -338,6 +352,9 @@ class AppLocalizationsEn extends AppLocalizations {
@override
String get buttonCancel => 'Cancel';
@override
String get buttonLearnMore => 'Learn more';
@override
String get buttonSave => 'Save';
@ -3159,6 +3176,14 @@ class AppLocalizationsEn extends AppLocalizations {
@override
String get federationNameLabel => 'Satellite name';
@override
String get federationAddIntro =>
'A satellite is another hub this hub connects to — its capabilities then become usable here in flows. You give it a name and receive a one-time token the satellite uses to enrol with this hub.';
@override
String get federationNameHelp =>
'A free-form name to recognize this satellite in the list (e.g. its location or purpose). Display only — it changes nothing technical.';
@override
String get federationIssueButton => 'Issue';

56
lib/pages/welcome.dart
View file

@ -1048,14 +1048,28 @@ class _DocEntry {
final IconData icon;
final String Function(AppLocalizations) title;
final String Function(AppLocalizations) blurb;
/// Whether this entry is shown as a card in the Welcome page's
/// doc grid. Every entry is reachable via [showFaiDoc] regardless;
/// `onWelcome: false` keeps advanced topics (federation, runs) out
/// of the newcomer grid while still wiring their page help buttons.
final bool onWelcome;
const _DocEntry({
required this.slug,
required this.icon,
required this.title,
required this.blurb,
this.onWelcome = true,
});
}
/// Every doc topic Studio can open in-app. The slug maps to
/// `assets/docs/<slug>[_<locale>].md`. Adding a page help button
/// (`showFaiDoc(context, '<slug>')`) requires a matching entry here
/// AND the asset files — `doc_help_wiring_test.dart` enforces both,
/// so a help button can never silently fall back to the wrong topic
/// again (federation/runs used to resolve to architecture).
final List<_DocEntry> _kDocs = <_DocEntry>[
_DocEntry(
slug: 'architecture',
@ -1087,17 +1101,47 @@ final List<_DocEntry> _kDocs = <_DocEntry>[
title: (l) => l.welcomeDocApprovalsTitle,
blurb: (l) => l.welcomeDocApprovalsBlurb,
),
_DocEntry(
slug: 'federation',
icon: Icons.hub_outlined,
title: (l) => l.welcomeDocFederationTitle,
blurb: (l) => l.welcomeDocFederationBlurb,
onWelcome: false,
),
_DocEntry(
slug: 'runs',
icon: Icons.rocket_launch_outlined,
title: (l) => l.welcomeDocRunsTitle,
blurb: (l) => l.welcomeDocRunsBlurb,
onWelcome: false,
),
];
/// The doc cards shown on the Welcome page (curated newcomer set).
final List<_DocEntry> _kWelcomeDocs =
_kDocs.where((d) => d.onWelcome).toList();
/// Slugs Studio can resolve in-app — exposed for the wiring guard
/// test so it can assert every `showFaiDoc` call has a home.
final Set<String> kKnownDocSlugs = _kDocs.map((d) => d.slug).toSet();
/// Public entry-point for the doc-reader sheet. Pass a slug
/// ("approvals", "audit", "security", "architecture", "flows")
/// and the bottom sheet opens with the localized markdown.
/// Returns null when the slug isn't registered — caller can
/// log + show a SnackBar.
Future<void>? showFaiDoc(BuildContext context, String slug) {
// A slug with no entry is a wiring bug (doc_help_wiring_test.dart
// guards against it). The fallback keeps the UI alive in release,
// but we assert in debug so the mistake surfaces during
// development rather than silently opening the wrong topic.
final entry = _kDocs.firstWhere(
(d) => d.slug == slug,
orElse: () => _kDocs.first,
orElse: () {
assert(false, 'showFaiDoc: unknown doc slug "$slug" — register it '
'in _kDocs and add assets/docs/$slug[_de].md');
return _kDocs.first;
},
);
return _DocReaderSheet.show(context, entry);
}
@ -1130,9 +1174,9 @@ class _DocsRow extends StatelessWidget {
if (!twoCols) {
return Column(
children: [
for (var i = 0; i < _kDocs.length; i++) ...[
for (var i = 0; i < _kWelcomeDocs.length; i++) ...[
if (i > 0) const SizedBox(height: ChainSpace.md),
_DocCard(entry: _kDocs[i]),
_DocCard(entry: _kWelcomeDocs[i]),
],
],
);
@ -1144,12 +1188,12 @@ class _DocsRow extends StatelessWidget {
// card spans the full width so it reads as intentional
// rather than a lonely half-box with dead space beside it.
final rows = <Widget>[];
for (var i = 0; i < _kDocs.length; i += 2) {
for (var i = 0; i < _kWelcomeDocs.length; i += 2) {
if (rows.isNotEmpty) {
rows.add(const SizedBox(height: ChainSpace.md));
}
final left = _kDocs[i];
final right = i + 1 < _kDocs.length ? _kDocs[i + 1] : null;
final left = _kWelcomeDocs[i];
final right = i + 1 < _kWelcomeDocs.length ? _kWelcomeDocs[i + 1] : null;
if (right == null) {
rows.add(_DocCard(entry: left));
} else {