Skip to content

Commit 6c60bac

Browse files
thymikeeclaude
andcommitted
refactor(contracts): one unavailableFact constructor for runtime refusals
Six local runtime owners spelled every refused operation as a four-line frozen literal; Vega and Linux each carried a private constructor for the same shape. The contracts package now owns it. Co-Authored-By: Claude Fable 5.1 <[email protected]>
1 parent e774595 commit 6c60bac

7 files changed

Lines changed: 364 additions & 475 deletions

File tree

‎packages/contracts/src/platform-runtime.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,16 @@ export type RuntimeOperationUnavailability = Readonly<{
134134

135135
export type RuntimeOperationFact = Readonly<{ available: true }> | RuntimeOperationUnavailability;
136136

137+
/** One frozen unavailable cell; owners list their refusals as calls instead of literals. */
138+
export function unavailableFact(
139+
reason: RuntimeOperationUnavailability['reason'],
140+
hint?: string,
141+
): RuntimeOperationUnavailability {
142+
return Object.freeze(
143+
hint === undefined ? { available: false, reason } : { available: false, reason, hint },
144+
);
145+
}
146+
137147
/**
138148
* An operation is present on a binding only when the owner's own facts admitted it. One helper so
139149
* every owner's `bind` reads as a list of admitted operations rather than a chain of branches —

‎packages/platform-android/src/runtime.ts‎

Lines changed: 99 additions & 124 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,11 @@ import {
2222
} from '@agent-device/contracts/gesture-admission';
2323
import { gestureRuntimeOperationFacts } from '@agent-device/contracts/gesture-runtime';
2424
import { scrollRuntimeOperationFacts } from '@agent-device/contracts/scroll-runtime';
25-
import { localRuntimeOwner, whenAdmitted } from '@agent-device/contracts/platform-runtime';
25+
import {
26+
localRuntimeOwner,
27+
unavailableFact,
28+
whenAdmitted,
29+
} from '@agent-device/contracts/platform-runtime';
2630
import { audioProbeRuntimeOperationFacts } from '@agent-device/contracts/audio-probe-runtime';
2731
import { perfRuntimeOperationFacts } from '@agent-device/contracts/perf-runtime';
2832
import { screenshotRuntimeOperationFacts } from '@agent-device/contracts/screenshot-runtime';
@@ -63,114 +67,91 @@ import {
6367

6468
const owner = localRuntimeOwner('android');
6569
const available = Object.freeze({ available: true } as const);
66-
const elementTextKindUnavailable = Object.freeze({
67-
available: false,
68-
reason: 'unsupported-device-kind',
69-
} as const);
70+
const elementTextKindUnavailable = unavailableFact('unsupported-device-kind');
7071
/**
7172
* Parity with the retired `focus` capability bucket (`{ emulator, device, unknown }`): every
7273
* Android kind drives touch through adb except the synthetic `simulator` row, which has no device.
7374
*/
74-
const focusKindUnavailable = Object.freeze({
75-
available: false,
76-
reason: 'unsupported-device-kind',
77-
hint: 'focus is supported on Android emulators and physical devices.',
78-
} as const);
75+
const focusKindUnavailable = unavailableFact(
76+
'unsupported-device-kind',
77+
'focus is supported on Android emulators and physical devices.',
78+
);
7979
/** adb drives keyboard actions on the same two kinds it drives everything else. */
80-
const keyboardKindUnavailable = Object.freeze({
81-
available: false,
82-
reason: 'unsupported-device-kind',
83-
hint: 'keyboard actions are supported on Android emulators and physical devices.',
84-
} as const);
85-
const hoverUnavailable = Object.freeze({
86-
available: false,
87-
reason: 'unsupported-platform-leaf',
88-
} as const);
80+
const keyboardKindUnavailable = unavailableFact(
81+
'unsupported-device-kind',
82+
'keyboard actions are supported on Android emulators and physical devices.',
83+
);
84+
const hoverUnavailable = unavailableFact('unsupported-platform-leaf');
8985
/**
9086
* `home` and `app-switcher` are the system buttons `input keyevent` can press. Any other (the
9187
* iPhone Action Button today) is hardware with no Android key event behind it, so there is no adb
9288
* path to admit even on the kinds every other Android cell admits.
9389
*/
94-
const systemButtonUnavailable = Object.freeze({
95-
available: false,
96-
reason: 'unsupported-platform-leaf',
97-
hint: 'Android has no key event for this system button.',
98-
} as const);
90+
const systemButtonUnavailable = unavailableFact(
91+
'unsupported-platform-leaf',
92+
'Android has no key event for this system button.',
93+
);
9994
/**
10095
* Foldable Android emulators do carry a posture control (the emulator console's `fold` and
10196
* `posture` commands), but nothing in this project drives it yet, so the cell refuses on every
10297
* kind rather than advertising a pose it cannot set.
10398
*/
104-
const foldUnavailable = Object.freeze({
105-
available: false,
106-
reason: 'unsupported-platform-leaf',
107-
hint: 'fold drives the hinge of a foldable iPhone simulator; the Android emulator posture control is not driven by agent-device yet.',
108-
} as const);
109-
const headlessUnavailable = Object.freeze({
110-
available: false,
111-
reason: 'unsupported-device-kind',
112-
hint: 'Headless boot is supported only for Android emulators.',
113-
} as const);
114-
const appStateUnavailable = Object.freeze({
115-
available: false,
116-
reason: 'unsupported-device-kind',
117-
hint: 'Android appstate is supported only for Android emulators and devices.',
118-
} as const);
119-
const prepareUnavailable = Object.freeze({
120-
available: false,
121-
reason: 'unsupported-platform-leaf',
122-
hint: 'Apple runner preparation is supported only for Apple targets.',
123-
} as const);
124-
const openTargetUnavailable = Object.freeze({
125-
available: false,
126-
reason: 'unsupported-device-kind',
127-
hint: 'open is supported only for Android emulators and devices.',
128-
} as const);
129-
const closeTargetUnavailable = Object.freeze({
130-
available: false,
131-
reason: 'unsupported-device-kind',
132-
hint: 'close is supported only for Android emulators and devices.',
133-
} as const);
134-
const runtimeHintsUnavailable = Object.freeze({
135-
available: false,
136-
reason: 'unsupported-device-kind',
137-
hint: 'Runtime hints are supported only for Android emulators and devices.',
138-
} as const);
139-
const portReverseUnavailable = Object.freeze({
140-
available: false,
141-
reason: 'unsupported-provider-mode',
142-
hint: 'Port reverse is supported only by an owning provider runtime.',
143-
} as const);
144-
const shutdownKindUnavailable = Object.freeze({
145-
available: false,
146-
reason: 'unsupported-device-kind',
147-
hint: 'shutdown is supported only for Apple simulators and Android emulators.',
148-
} as const);
149-
const screenshotKindUnavailable = Object.freeze({
150-
available: false,
151-
reason: 'unsupported-device-kind',
152-
hint: 'screenshot is supported only for Android emulators and devices.',
153-
} as const);
154-
const snapshotKindUnavailable = Object.freeze({
155-
available: false,
156-
reason: 'unsupported-device-kind',
157-
hint: 'snapshot is supported only for Android emulators and devices.',
158-
} as const);
159-
const snapshotCustomActionsUnavailable = Object.freeze({
160-
available: false,
161-
reason: 'unsupported-platform-leaf',
162-
hint: 'Re-run without --actions, or target an iOS simulator.',
163-
} as const);
164-
const viewportUnavailable = Object.freeze({
165-
available: false,
166-
reason: 'unsupported-platform-leaf',
167-
hint: 'viewport resizes web targets only (--platform web).',
168-
} as const);
169-
const audioQueryUnavailable = Object.freeze({
170-
available: false,
171-
reason: 'unsupported-platform-leaf',
172-
hint: 'the stateless audio page probe is a web-session operation; Android targets use the host capture.',
173-
} as const);
99+
const foldUnavailable = unavailableFact(
100+
'unsupported-platform-leaf',
101+
'fold drives the hinge of a foldable iPhone simulator; the Android emulator posture control is not driven by agent-device yet.',
102+
);
103+
const headlessUnavailable = unavailableFact(
104+
'unsupported-device-kind',
105+
'Headless boot is supported only for Android emulators.',
106+
);
107+
const appStateUnavailable = unavailableFact(
108+
'unsupported-device-kind',
109+
'Android appstate is supported only for Android emulators and devices.',
110+
);
111+
const prepareUnavailable = unavailableFact(
112+
'unsupported-platform-leaf',
113+
'Apple runner preparation is supported only for Apple targets.',
114+
);
115+
const openTargetUnavailable = unavailableFact(
116+
'unsupported-device-kind',
117+
'open is supported only for Android emulators and devices.',
118+
);
119+
const closeTargetUnavailable = unavailableFact(
120+
'unsupported-device-kind',
121+
'close is supported only for Android emulators and devices.',
122+
);
123+
const runtimeHintsUnavailable = unavailableFact(
124+
'unsupported-device-kind',
125+
'Runtime hints are supported only for Android emulators and devices.',
126+
);
127+
const portReverseUnavailable = unavailableFact(
128+
'unsupported-provider-mode',
129+
'Port reverse is supported only by an owning provider runtime.',
130+
);
131+
const shutdownKindUnavailable = unavailableFact(
132+
'unsupported-device-kind',
133+
'shutdown is supported only for Apple simulators and Android emulators.',
134+
);
135+
const screenshotKindUnavailable = unavailableFact(
136+
'unsupported-device-kind',
137+
'screenshot is supported only for Android emulators and devices.',
138+
);
139+
const snapshotKindUnavailable = unavailableFact(
140+
'unsupported-device-kind',
141+
'snapshot is supported only for Android emulators and devices.',
142+
);
143+
const snapshotCustomActionsUnavailable = unavailableFact(
144+
'unsupported-platform-leaf',
145+
'Re-run without --actions, or target an iOS simulator.',
146+
);
147+
const viewportUnavailable = unavailableFact(
148+
'unsupported-platform-leaf',
149+
'viewport resizes web targets only (--platform web).',
150+
);
151+
const audioQueryUnavailable = unavailableFact(
152+
'unsupported-platform-leaf',
153+
'the stateless audio page probe is a web-session operation; Android targets use the host capture.',
154+
);
174155

175156
function androidLifecycleFacts(device: DeviceInfo) {
176157
const openTarget = androidOpenTargetFact(device);
@@ -205,21 +186,18 @@ function androidRuntimeHintsFact(device: DeviceInfo) {
205186
: runtimeHintsUnavailable;
206187
}
207188

208-
const gestureKindUnavailable = Object.freeze({
209-
available: false,
210-
reason: 'unsupported-device-kind',
211-
hint: 'Gestures are supported on Android emulators and physical devices.',
212-
} as const);
213-
const androidTvMultiTouchUnavailable = Object.freeze({
214-
available: false,
215-
reason: 'unsupported-platform-leaf',
216-
hint: ANDROID_TV_MULTI_TOUCH_UNSUPPORTED_HINT,
217-
} as const);
218-
const androidTvDragUnavailable = Object.freeze({
219-
available: false,
220-
reason: 'unsupported-platform-leaf',
221-
hint: TARGET_AUTHORED_DRAG_UNSUPPORTED_HINT,
222-
} as const);
189+
const gestureKindUnavailable = unavailableFact(
190+
'unsupported-device-kind',
191+
'Gestures are supported on Android emulators and physical devices.',
192+
);
193+
const androidTvMultiTouchUnavailable = unavailableFact(
194+
'unsupported-platform-leaf',
195+
ANDROID_TV_MULTI_TOUCH_UNSUPPORTED_HINT,
196+
);
197+
const androidTvDragUnavailable = unavailableFact(
198+
'unsupported-platform-leaf',
199+
TARGET_AUTHORED_DRAG_UNSUPPORTED_HINT,
200+
);
223201

224202
/**
225203
* A TV target has no touch input at all, which is the one Android gate the retired admission
@@ -240,11 +218,10 @@ function androidTouchFact(device: DeviceInfo) {
240218
return device.kind === 'simulator' ? focusKindUnavailable : available;
241219
}
242220

243-
const clipboardShellUnavailable = Object.freeze({
244-
available: false,
245-
reason: 'owner-capability-missing',
246-
hint: ANDROID_CLIPBOARD_SHELL_COMMAND_UNAVAILABLE_HINT,
247-
} as const);
221+
const clipboardShellUnavailable = unavailableFact(
222+
'owner-capability-missing',
223+
ANDROID_CLIPBOARD_SHELL_COMMAND_UNAVAILABLE_HINT,
224+
);
248225

249226
/**
250227
* The probe could not reach the device, so this owner does not know whether the build supports a
@@ -253,11 +230,10 @@ const clipboardShellUnavailable = Object.freeze({
253230
* exact failure fact-based admission exists to prevent. Deliberately not cached — the next
254231
* inspection asks again.
255232
*/
256-
const clipboardShellUnknown = Object.freeze({
257-
available: false,
258-
reason: 'owner-capability-missing',
259-
hint: 'Could not determine whether this Android build supports a shell clipboard: the adb probe did not complete. Retry once the device is reachable.',
260-
} as const);
233+
const clipboardShellUnknown = unavailableFact(
234+
'owner-capability-missing',
235+
'Could not determine whether this Android build supports a shell clipboard: the adb probe did not complete. Retry once the device is reachable.',
236+
);
261237

262238
/**
263239
* `probe-failed` covers both ways this owner can end up without an answer: the probe ran and could
@@ -273,11 +249,10 @@ async function probeClipboardShellSupport(
273249
return await probe.call(host.androidTools, device);
274250
}
275251

276-
const tvRemoteUnavailable = Object.freeze({
277-
available: false,
278-
reason: 'unsupported-device-kind',
279-
hint: 'tv-remote is supported only on Android TV targets.',
280-
} as const);
252+
const tvRemoteUnavailable = unavailableFact(
253+
'unsupported-device-kind',
254+
'tv-remote is supported only on Android TV targets.',
255+
);
281256
/**
282257
* Parity with the retired `androidPlugin` closure: the TV-target gate, whose hint fired
283258
* regardless of device kind (the closure never distinguished the synthetic `simulator` row from

0 commit comments

Comments
 (0)