The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:harness/logging/debug_surface.dart';
import 'package:harness/shortcuts/app_shortcuts.dart';
import 'package:xterm/xterm.dart';
void main() {
group('shortcuts survive a focused terminal', () {
// The whole design rests on this: the main pane is a real terminal that
// takes the keyboard, and a shortcut bound above it has to still fire.
// If xterm ever swallows ⌘ keys, every binding here goes silently dead.
Future<int> pressWithTerminalFocused(
WidgetTester tester,
LogicalKeyboardKey key, {
bool shift = false,
bool alt = false,
TargetPlatform? platform,
}) async {
// Off by default, and worth naming when it matters: a widget test runs as
// Android unless told otherwise, so an Apple-gated branch in the terminal
// is invisible here — which is exactly how ⌘ came to be the app's
// modifier on macOS and the terminal's on Linux.
debugDefaultTargetPlatformOverride = platform;
var fired = 0;
final terminal = Terminal();
await tester.pumpWidget(
MaterialApp(
home: CallbackShortcuts(
bindings: {
SingleActivator(key, meta: true, shift: shift, alt: alt): () =>
fired++,
},
child: Scaffold(body: TerminalView(terminal, autofocus: true)),
),
),
);
await tester.pump();
await tester.sendKeyDownEvent(LogicalKeyboardKey.meta);
if (shift) await tester.sendKeyDownEvent(LogicalKeyboardKey.shift);
if (alt) await tester.sendKeyDownEvent(LogicalKeyboardKey.alt);
await tester.sendKeyEvent(key);
if (alt) await tester.sendKeyUpEvent(LogicalKeyboardKey.alt);
if (shift) await tester.sendKeyUpEvent(LogicalKeyboardKey.shift);
await tester.sendKeyUpEvent(LogicalKeyboardKey.meta);
await tester.pump();
debugDefaultTargetPlatformOverride = null;
return fired;
}
testWidgets('a plain ⌘ key reaches the binding', (tester) async {
expect(
await pressWithTerminalFocused(tester, LogicalKeyboardKey.keyN),
1,
);
});
testWidgets('⌘⇧ reaches the binding', (tester) async {
expect(
await pressWithTerminalFocused(
tester,
LogicalKeyboardKey.bracketRight,
shift: true,
),
1,
);
});
testWidgets('a bracket chord reaches the binding', (tester) async {
expect(
await pressWithTerminalFocused(tester, LogicalKeyboardKey.bracketRight),
1,
);
});
testWidgets('⌘ + arrow reaches it too, on either desktop', (tester) async {
// This used to read 0, with a note that xterm answers every arrow itself
// so an arrow binding would be dead on arrival. That was never true of
// the platform the app ships on: the terminal already let ⌘ chords go
// past on macOS, and only there — the 0 was the Linux behaviour, seen
// because a widget test runs as Android. Now the escape is uniform, so
// pin it on both, arrows included: with ⌘ held, nothing reaches the pty.
//
// Arrows still go unbound in appShortcuts() ('no shortcut is bound to an
// arrow key' below), but that is now a choice about what the hand expects
// a terminal to do — not a limit on what can be bound.
for (final platform in [TargetPlatform.macOS, TargetPlatform.linux]) {
expect(
await pressWithTerminalFocused(
tester,
LogicalKeyboardKey.arrowRight,
platform: platform,
),
1,
reason: '⌘→ must not be answered by the terminal on $platform',
);
expect(
await pressWithTerminalFocused(
tester,
LogicalKeyboardKey.arrowLeft,
alt: true,
platform: platform,
),
1,
reason: '⌘⌥← must not be answered by the terminal on $platform',
);
}
});
testWidgets('a bare key still goes to the terminal, not to a shortcut', (
tester,
) async {
// The other half of the contract: taking ⌘ must not cost the agent the
// letters someone is typing at it.
var fired = 0;
final terminal = Terminal();
final typed = <String>[];
terminal.onOutput = typed.add;
await tester.pumpWidget(
MaterialApp(
home: CallbackShortcuts(
bindings: {
const SingleActivator(LogicalKeyboardKey.keyN): () => fired++,
},
child: Scaffold(body: TerminalView(terminal, autofocus: true)),
),
),
);
await tester.pump();
await tester.sendKeyEvent(LogicalKeyboardKey.keyN);
await tester.pump();
expect(fired, 0, reason: 'the terminal must win a bare key');
});
});
group('the declared set', () {
test('no two shortcuts claim the same chord', () {
final seen = <String>{};
for (final shortcut in appShortcuts()) {
final chord = describeShortcut(shortcut.activator);
expect(seen.add(chord), isTrue, reason: '$chord is bound twice');
}
});
test('nothing is bound with Control but the tab pair, or with Option alone', () {
// Ctrl belongs to tmux and the shell; Option alone is how a terminal
// sends Meta, which is why ⌥⏎ reaches the engine.
//
// ⌃⇥ / ⌃⇧⇥ are the single exception (they walk AGENTS now), pinned by CHORD rather than
// waved through by action: the terminal is made to let exactly that pair
// past (see terminal_view.dart) because no shell or tmux binding uses it,
// and it is the pair every tabbed app trains people to reach for.
// app_shortcuts.dart carries the full argument.
//
// By chord and not by trigger key, which is the stronger of the two ways
// this has been written: "trigger is Tab, so Ctrl is allowed" would wave
// ⌃⌥⇥ through as well, and the point of pinning is that a THIRD Ctrl
// chord still fails.
const ctrlAllowed = {'⌃⇥', '⌃⇧⇥'};
for (final shortcut in appShortcuts()) {
final chord = describeShortcut(shortcut.activator);
if (shortcut.activator.control) {
expect(
ctrlAllowed.contains(chord),
isTrue,
reason: '${shortcut.label} takes a Ctrl key the shell needs',
);
// The Ctrl twin of a ⌘ chord, never both at once.
expect(
shortcut.activator.meta,
isFalse,
reason: '${shortcut.label} is the Ctrl twin of a ⌘ chord, not both',
);
continue;
}
expect(
shortcut.activator.meta,
isTrue,
reason: '${shortcut.label} must be a ⌘ chord',
);
}
});
test('no shortcut takes a BARE arrow key', () {
// Bare arrows belong to the terminal — the cursor and shell history are
// the first thing anyone presses them for. A ⌘ chord is the app's: the
// terminal passes everything but ⌘V straight up
// (terminal_panel._onTerminalKey), which is what lets ⌘← / ⌘→ walk the
// grid the way the brackets already do.
final arrows = {
LogicalKeyboardKey.arrowLeft,
LogicalKeyboardKey.arrowRight,
LogicalKeyboardKey.arrowUp,
LogicalKeyboardKey.arrowDown,
};
for (final shortcut in appShortcuts()) {
if (shortcut.activator.meta) continue;
expect(
arrows.contains(shortcut.activator.trigger),
isFalse,
reason: '${shortcut.label} would be swallowed by the terminal',
);
}
});
test('does not take the three chords xterm already owns on macOS', () {
const claimedByTerminal = {'⌘C', '⌘V', '⌘A'};
for (final shortcut in appShortcuts()) {
expect(
claimedByTerminal.contains(describeShortcut(shortcut.activator)),
isFalse,
reason: '${shortcut.label} would steal copy/paste/select-all',
);
}
});
test('every declared shortcut gets a binding when a handler exists', () {
final bindings = buildShortcutBindings(
handlers: {for (final s in appShortcuts()) s.action: () {}},
onSelectTabIndex: (_) {},
);
expect(bindings.length, appShortcuts().length + kTabDigitCount);
});
chordsFor(ShortcutAction a) => appShortcuts()
.where((s) => s.action == a)
.map((s) => describeShortcut(s.activator))
.toList();
test('Command-arrows focus panes and Shift moves them', () {
expect(chordsFor(ShortcutAction.focusPaneLeft), ['⌘H', '⌘←']);
expect(chordsFor(ShortcutAction.focusPaneBelow), ['⌘J', '⌘↓']);
expect(chordsFor(ShortcutAction.focusPaneAbove), ['⌘K', '⌘↑']);
expect(chordsFor(ShortcutAction.focusPaneRight), ['⌘L', '⌘→']);
expect(chordsFor(ShortcutAction.movePaneLeft), ['⇧⌘←']);
expect(chordsFor(ShortcutAction.movePaneDown), ['⇧⌘↓']);
expect(chordsFor(ShortcutAction.movePaneUp), ['⇧⌘↑']);
expect(chordsFor(ShortcutAction.movePaneRight), ['⇧⌘→']);
});
test('brackets walk agents, and ⌥⌘ arrows walk tabs', () {
// They used to carry three verbs told apart only by modifiers: ⌘[ ] walked
// panes, ⇧⌘[ ] walked agents, ⌥⌘[ ] moved panes. Panes use arrows, so
// the brackets keep the one job a bracket is good at. Tabs moved off
// ⇧⌘[ ] to ⌥⌘←/→, the key Safari and Chrome walk tabs with.
final bracketed = <ShortcutAction>{};
for (final s in appShortcuts()) {
final chord = describeShortcut(s.activator);
if (chord.contains('[') || chord.contains(']')) bracketed.add(s.action);
}
expect(bracketed, {
ShortcutAction.previousAgent,
ShortcutAction.nextAgent,
});
expect(chordsFor(ShortcutAction.nextSwarm), contains('⌥⌘→'));
expect(chordsFor(ShortcutAction.previousSwarm), contains('⌥⌘←'));
});
test('the terminal verbs tmux trained people on are all here', () {
expect(chordsFor(ShortcutAction.zoomPane), contains('⌘⏎'));
// The previous-pane command remains available through remapping.
expect(chordsFor(ShortcutAction.lastPane), isEmpty);
expect(chordsFor(ShortcutAction.newSwarm), ['⌘T']);
expect(chordsFor(ShortcutAction.showLayout), ['⇧⌘L']);
expect(chordsFor(ShortcutAction.orchestrate), isEmpty);
expect(chordsFor(ShortcutAction.routeTask), ['⌘B']);
expect(chordsFor(ShortcutAction.addAgent), ['⌘O']);
expect(chordsFor(ShortcutAction.newAgent), ['⌘N']);
expect(chordsFor(ShortcutAction.showAttention), ['⇧⌘I']);
expect(chordsFor(ShortcutAction.findTerminal), ['⌘F']);
expect(chordsFor(ShortcutAction.findNext), ['⌘G']);
expect(chordsFor(ShortcutAction.findPrevious), ['⇧⌘G']);
});
test(
'a shortcut with no handler is left unbound, not bound to nothing',
() {
final bindings = buildShortcutBindings(handlers: const {});
expect(bindings, isEmpty);
},
);
});
group('the rows the UI prints', () {
test('two chords for one action are one row, not two', () {
// Alternate history keys share one help row.
final rows = shortcutRows();
final labels = rows.map((row) => row.label).toList();
expect(labels.toSet().length, labels.length, reason: 'a label repeats');
final right = rows.firstWhere(
(row) => row.label == 'Focus the pane to the right',
);
expect(right.chords, [
['⌘', 'L'],
['⌘', '→'],
]);
final next = rows.firstWhere((row) => row.label == 'Next Tab');
expect(next.chords, [
['⌥', '⌘', '→'],
['⌃', '⇥'],
]);
});
test('every declared shortcut reaches a row', () {
final rows = shortcutRows();
for (final shortcut in appShortcuts()) {
final row = rows.firstWhere((row) => row.label == shortcut.label);
expect(
row.chords,
contains(equals(describeShortcutKeys(shortcut.activator))),
reason: '${shortcut.label} is bound but not printed',
);
}
});
test('the digits are one row, at the end of their own group', () {
final rows = shortcutRows();
final digits = rows.indexWhere((row) => row.label == 'Select tabs 1–9');
expect(digits, isNot(-1));
expect(rows[digits].chords, [
['⌘', '1 – 9'],
]);
// Digits select tabs; directional shortcuts stay in the pane layout.
expect(rows[digits].group, ShortcutGroup.navigate);
// Last of its group, so it does not split the group it belongs to.
expect(
digits == rows.length - 1 ||
rows[digits + 1].group != ShortcutGroup.navigate,
isTrue,
);
});
test('a chord is split into the keys a keyboard has', () {
expect(
describeShortcutKeys(
const SingleActivator(
LogicalKeyboardKey.bracketRight,
meta: true,
shift: true,
),
),
['⇧', '⌘', ']'],
);
// Tab prints as ⇥, the way a Mac menu prints it — `keyLabel` says 'Tab'.
expect(
describeShortcutKeys(
const SingleActivator(LogicalKeyboardKey.tab, control: true),
),
['⌃', '⇥'],
);
});
});
group('the developer shortcut', () {
// ⇧⌘D opens Settings ▸ Debug. It is the one shortcut that is not always
// there — a release build has no Debug screen — so what is guarded is that
// the list and the build agree, in both directions.
test(
'is declared only where the debug surface is, and a test build is',
() {
expect(kDebugSurfaceEnabled, isTrue, reason: 'tests run in debug mode');
expect(appShortcuts(), contains(kDebugShortcut));
expect(kAppShortcuts, isNot(contains(kDebugShortcut)));
expect(describeShortcut(kDebugShortcut.activator), '⇧⌘D');
},
);
test('reaches a binding and a printed row like any other', () {
final bindings = buildShortcutBindings(
handlers: {ShortcutAction.showDebug: () {}},
);
expect(bindings.containsKey(kDebugShortcut.activator), isTrue);
expect(shortcutHintFor(ShortcutAction.showDebug), '⇧⌘D');
expect(
shortcutRows().map((row) => row.label),
contains(kDebugShortcut.label),
);
});
});
}