Skip to content

Commit c621cfb

Browse files
committed
refactor(commands): declare a command option once and derive its surfaces
Collapses the pass-through hops the #2410 hop trace named, so an option is stated once and every surface reads that statement instead of a copy. - The snapshot option/flag pair (`customActions` <-> `snapshotCustomActions` and its seven siblings) is declared once in `@agent-device/kernel/snapshot` with both projections, generalising the shipped screenshot pair. The nine hand-written renames now read the declaration. - The dispatch pass-through flags are declared once as `DISPATCH_CONTEXT_FLAG_KEYS`; `DispatchContext` and the daemon's `contextFromFlags` both derive from it, so an identically-named flag no longer costs two files. The mapper keeps only what it decides. - The snapshot capture option keys are one type (`SnapshotCommandOptionFields`), referenced by the public SDK options, the internal request bag and the command runtime options instead of four copies. - An option's prose has one owner: its `FlagDefinition` now carries both audiences (`usageDescription` for --help, `inputDescription` for the tool and SDK field), and `optionField` derives the command's input field -- its JSON schema shape, bounds and description -- from that declaration. The duplicate doc comments in contracts are gone. Adds planted-divergence tests: a divergence planted in the one declaration must move the derived surface, which a second hand-written copy could not do. No help text, MCP tool schema or wire shape changes.
1 parent 9d7d60c commit c621cfb

21 files changed

Lines changed: 527 additions & 189 deletions

‎packages/contracts/src/cli-flags.ts‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,12 @@ import type { ScreenshotRequestFlags } from './screenshot.ts';
2323
import type { RecordingScope } from './recording-scope.ts';
2424
import type { ReplayRequestFields } from './replay-request-fields.ts';
2525

26+
// This is the flag KEY vocabulary, not where an option is described: an
27+
// option's prose belongs to its one declaration (its `FlagDefinition`, which
28+
// carries both the `--help` and the tool/SDK audience), so a doc comment
29+
// repeated here would be a second copy that drifts. Comments below state only
30+
// facts this type alone knows — that a key has no CLI token, or how two keys
31+
// interact.
2632
export type CliFlags = CloudProviderProfileFields &
2733
RemoteConfigMetroOptions &
2834
ScreenshotRequestFlags &
@@ -120,11 +126,6 @@ export type CliFlags = CloudProviderProfileFields &
120126
saveScript?: boolean | string;
121127
shutdown?: boolean;
122128
relaunch?: boolean;
123-
/**
124-
* Include the initial interactive snapshot in a fresh open response. With
125-
* no app argument, iOS can discover the sole running app on the sole booted
126-
* simulator and fails closed when that environment is ambiguous.
127-
*/
128129
foreground?: boolean;
129130
surface?: SessionSurface;
130131
headless?: boolean;

‎packages/contracts/src/client-app.ts‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -68,11 +68,8 @@ export type AppOpenOptions = AgentDeviceRequestOverrides &
6868
relaunch?: boolean;
6969
/** Startup budget in milliseconds: bounds the Simulator boot wait on a cold device. */
7070
timeoutMs?: number;
71-
/**
72-
* Include the initial interactive snapshot in a fresh open response. With
73-
* no app argument, iOS can discover the sole running app on the sole booted
74-
* simulator and fails closed when that environment is ambiguous.
75-
*/
71+
// `foreground` is described once on its option declaration (the `--foreground`
72+
// FlagDefinition), which feeds both `--help` and the tool/SDK field.
7673
foreground?: boolean;
7774
saveScript?: boolean | string;
7875
/** #1258: overwrite an existing --save-script target instead of refusing. Alias: --overwrite. */

‎packages/contracts/src/client-capture.ts‎

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import type { SessionSurface } from './session-surface.ts';
44
import type { PublicSnapshotCaptureAnnotations } from './snapshot-capture-annotations.ts';
55
import type { SnapshotDiagnosticsSummary } from './snapshot-diagnostics.ts';
66
import type {
7+
SnapshotCommandOptionFields,
78
SnapshotNode,
89
SnapshotUnchanged,
910
SnapshotVisibility,
@@ -16,15 +17,12 @@ import type {
1617
DeviceCommandBaseOptions,
1718
} from './client-connection.ts';
1819

20+
// The snapshot capture keys come from the one snapshot option declaration
21+
// (`SnapshotCommandOptionFields`); their prose lives on the owning option
22+
// declaration, not on a second copy here.
1923
export type CaptureSnapshotOptions = AgentDeviceRequestOverrides &
20-
AgentDeviceSelectionOptions & {
21-
interactiveOnly?: boolean;
22-
depth?: number;
23-
scope?: string;
24-
raw?: boolean;
25-
/** List accessibility custom actions on merged elements (iOS simulator). */
26-
customActions?: boolean;
27-
forceFull?: boolean;
24+
AgentDeviceSelectionOptions &
25+
SnapshotCommandOptionFields & {
2826
timeoutMs?: number;
2927
/**
3028
* #1271 stage 2 (ADR 0012 amendment): `snapshot` is observation-only and

‎packages/contracts/src/client-request.ts‎

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -14,24 +14,20 @@ import type {
1414
NetworkIncludeMode,
1515
SessionRuntimeHints,
1616
} from '@agent-device/kernel/contracts';
17+
import type { SnapshotCommandOptionFields } from '@agent-device/kernel/snapshot';
1718
import type { DaemonBatchStep } from './batch-step.ts';
1819
import type { ReplayRequestFields } from './replay-request-fields.ts';
1920
import type { AgentDeviceClientConfig, AgentDeviceSelectionOptions } from './client-connection.ts';
2021

2122
export type CommandExecutionOptions = Partial<ScreenshotRequestFlags> &
22-
ReplayRequestFields & {
23+
ReplayRequestFields &
24+
SnapshotCommandOptionFields & {
2325
positionals?: string[];
2426
kind?: string;
2527
out?: string;
2628
artifact?: string;
2729
dsym?: string;
2830
searchPath?: string;
29-
interactiveOnly?: boolean;
30-
depth?: number;
31-
scope?: string;
32-
raw?: boolean;
33-
customActions?: boolean;
34-
forceFull?: boolean;
3531
count?: number;
3632
fps?: number;
3733
recordingScope?: RecordingScope;

‎packages/kernel/src/snapshot.ts‎

Lines changed: 130 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -87,14 +87,137 @@ export type SnapshotOptions = {
8787
customActions?: boolean;
8888
};
8989

90-
export type SnapshotPresentationFlagInput = {
91-
snapshotInteractiveOnly?: boolean;
92-
snapshotDepth?: number;
93-
snapshotScope?: string;
94-
snapshotRaw?: boolean;
95-
snapshotCustomActions?: boolean;
90+
/**
91+
* The snapshot capture family stated ONCE as option key ↔ command-flag key.
92+
*
93+
* The same pair (`customActions` ↔ `snapshotCustomActions`, and its seven
94+
* siblings) used to be re-typed by hand at every seam that carries a snapshot
95+
* request across the option/flag vocabulary line — the CLI reader, the client
96+
* option projection, the daemon capture inputs, the presentation key. Each copy
97+
* restated a fact already stated here and decided nothing, so a new snapshot
98+
* option cost one edit per seam and a missed seam dropped the option silently.
99+
*
100+
* Declared in the kernel because both vocabularies are declared here
101+
* ({@link SnapshotOptions}) and above (`CommandFlags` in contracts), so this is
102+
* the lowest point both sides can read. This generalises the shipped
103+
* `screenshotFlagsFromOptions`/`screenshotOptionsFromFlags` pair for the
104+
* screenshot family.
105+
*
106+
* Every projection takes an EXPLICIT key list: a seam admits the options it
107+
* routes and no more, so adding a pair here never silently widens a seam that
108+
* cannot honour it.
109+
*/
110+
// Exported only because the exported types below say `typeof` it.
111+
// fallow-ignore-next-line unused-export
112+
export const SNAPSHOT_OPTION_FLAGS = {
113+
interactiveOnly: 'snapshotInteractiveOnly',
114+
depth: 'snapshotDepth',
115+
scope: 'snapshotScope',
116+
raw: 'snapshotRaw',
117+
customActions: 'snapshotCustomActions',
118+
forceFull: 'snapshotForceFull',
119+
includeHiddenContentHints: 'snapshotIncludeHiddenContentHints',
120+
preferredBackend: 'snapshotPreferredBackend',
121+
} as const;
122+
123+
export type SnapshotOptionKey = keyof typeof SNAPSHOT_OPTION_FLAGS;
124+
125+
type SnapshotOptionValues = {
126+
interactiveOnly: boolean;
127+
depth: number;
128+
scope: string;
129+
raw: boolean;
130+
customActions: boolean;
131+
forceFull: boolean;
132+
includeHiddenContentHints: boolean;
133+
preferredBackend: SnapshotPreferredBackend;
134+
};
135+
136+
/** The option-vocabulary view of the declared pairs, narrowed to `TKeys`. */
137+
export type SnapshotOptionFields<TKeys extends SnapshotOptionKey = SnapshotOptionKey> = {
138+
[TKey in TKeys]?: SnapshotOptionValues[TKey];
139+
};
140+
141+
/** The flag-vocabulary view of the declared pairs, narrowed to `TKeys`. */
142+
export type SnapshotOptionFlagFields<TKeys extends SnapshotOptionKey = SnapshotOptionKey> = {
143+
[TKey in TKeys as (typeof SNAPSHOT_OPTION_FLAGS)[TKey]]?: SnapshotOptionValues[TKey];
96144
};
97145

146+
/**
147+
* Option keys a `snapshot`/`diff` command request carries end to end. `scope` is
148+
* resolved against the session before capture, so seams that resolve it spread
149+
* this projection and then override that one key.
150+
*/
151+
export const SNAPSHOT_COMMAND_OPTION_KEYS = [
152+
'interactiveOnly',
153+
'depth',
154+
'scope',
155+
'raw',
156+
'customActions',
157+
'forceFull',
158+
] as const;
159+
160+
/**
161+
* The snapshot capture options a `snapshot`/`diff` request is stated in, in
162+
* every vocabulary that names them: the public SDK type, the internal request
163+
* bag and the command runtime options each reference THIS type instead of
164+
* re-listing the same six keys.
165+
*/
166+
export type SnapshotCommandOptionFields = SnapshotOptionFields<
167+
(typeof SNAPSHOT_COMMAND_OPTION_KEYS)[number]
168+
>;
169+
170+
/** Option keys a daemon runtime capture input carries; `forceFull` is a command-level concern. */
171+
export const SNAPSHOT_CAPTURE_OPTION_KEYS = [
172+
'interactiveOnly',
173+
'preferredBackend',
174+
'depth',
175+
'scope',
176+
'raw',
177+
'customActions',
178+
'includeHiddenContentHints',
179+
] as const;
180+
181+
/** Option keys that identify a presentation; see {@link buildSnapshotPresentationKey}. */
182+
// fallow-ignore-next-line unused-export
183+
export const SNAPSHOT_PRESENTATION_OPTION_KEYS = [
184+
'depth',
185+
'interactiveOnly',
186+
'raw',
187+
'scope',
188+
'customActions',
189+
] as const;
190+
191+
/**
192+
* Reads the declared options out of a flags bag. Every requested key is present
193+
* (possibly `undefined`), matching what the hand-written copies produced.
194+
*/
195+
export function snapshotOptionsFromFlags<const TKeys extends readonly SnapshotOptionKey[]>(
196+
flags: SnapshotOptionFlagFields | undefined,
197+
keys: TKeys,
198+
): SnapshotOptionFields<TKeys[number]> {
199+
return Object.fromEntries(
200+
keys.map((key) => [key, flags?.[SNAPSHOT_OPTION_FLAGS[key]]]),
201+
) as SnapshotOptionFields<TKeys[number]>;
202+
}
203+
204+
/** Writes the declared options back into flag vocabulary, dropping absent values. */
205+
export function snapshotFlagsFromOptions<const TKeys extends readonly SnapshotOptionKey[]>(
206+
options: SnapshotOptionFields | undefined,
207+
keys: TKeys,
208+
): SnapshotOptionFlagFields<TKeys[number]> {
209+
return Object.fromEntries(
210+
keys.flatMap((key) => {
211+
const value = options?.[key];
212+
return value === undefined ? [] : [[SNAPSHOT_OPTION_FLAGS[key], value]];
213+
}),
214+
) as SnapshotOptionFlagFields<TKeys[number]>;
215+
}
216+
217+
export type SnapshotPresentationFlagInput = SnapshotOptionFlagFields<
218+
(typeof SNAPSHOT_PRESENTATION_OPTION_KEYS)[number]
219+
>;
220+
98221
export type RawSnapshotNode = {
99222
index: number;
100223
type?: string;
@@ -382,13 +505,7 @@ export function snapshotPresentationOptionsFromFlags(
382505
flags: SnapshotPresentationFlagInput | undefined,
383506
): SnapshotOptions | undefined {
384507
if (!flags) return undefined;
385-
return {
386-
depth: flags.snapshotDepth,
387-
interactiveOnly: flags.snapshotInteractiveOnly,
388-
raw: flags.snapshotRaw,
389-
scope: flags.snapshotScope,
390-
customActions: flags.snapshotCustomActions,
391-
};
508+
return snapshotOptionsFromFlags(flags, SNAPSHOT_PRESENTATION_OPTION_KEYS);
392509
}
393510

394511
export function centerOfRect(rect: Rect): Point {

‎src/backend-snapshot-options.ts‎

Lines changed: 20 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,28 @@
1-
import type { CommandFlags } from '@agent-device/contracts/command';
1+
import { snapshotFlagsFromOptions } from '@agent-device/kernel/snapshot';
22
import type { BackendSnapshotOptions } from './backend.ts';
33

44
type RoutedSnapshotOption = keyof Omit<BackendSnapshotOptions, 'includeRects' | 'outPath'>;
55

6-
const SNAPSHOT_OPTION_FLAGS = {
7-
interactiveOnly: 'snapshotInteractiveOnly',
8-
scope: 'snapshotScope',
9-
depth: 'snapshotDepth',
10-
raw: 'snapshotRaw',
11-
customActions: 'snapshotCustomActions',
12-
includeHiddenContentHints: 'snapshotIncludeHiddenContentHints',
13-
preferredBackend: 'snapshotPreferredBackend',
14-
} as const satisfies Record<RoutedSnapshotOption, keyof CommandFlags>;
6+
/**
7+
* Which backend snapshot options route as request flags. Still pinned to
8+
* `BackendSnapshotOptions`, so a new backend option must decide whether it
9+
* routes; the option→flag pairing itself is declared once in the kernel and is
10+
* no longer restated here.
11+
*/
12+
const ROUTED_SNAPSHOT_OPTIONS = {
13+
interactiveOnly: true,
14+
scope: true,
15+
depth: true,
16+
raw: true,
17+
customActions: true,
18+
includeHiddenContentHints: true,
19+
preferredBackend: true,
20+
} as const satisfies Record<RoutedSnapshotOption, true>;
1521

16-
type SnapshotFlagOverrides = Partial<
17-
Pick<CommandFlags, (typeof SNAPSHOT_OPTION_FLAGS)[RoutedSnapshotOption]>
22+
const ROUTED_SNAPSHOT_OPTION_KEYS = Object.keys(ROUTED_SNAPSHOT_OPTIONS) as ReadonlyArray<
23+
keyof typeof ROUTED_SNAPSHOT_OPTIONS
1824
>;
1925

20-
export function snapshotOptionsToFlags(
21-
options: BackendSnapshotOptions | undefined,
22-
): SnapshotFlagOverrides {
23-
if (!options) return {};
24-
return Object.fromEntries(
25-
Object.entries(SNAPSHOT_OPTION_FLAGS).flatMap(([optionKey, flagKey]) => {
26-
const value = options[optionKey as RoutedSnapshotOption];
27-
return value === undefined ? [] : [[flagKey, value]];
28-
}),
29-
) as SnapshotFlagOverrides;
26+
export function snapshotOptionsToFlags(options: BackendSnapshotOptions | undefined) {
27+
return snapshotFlagsFromOptions(options, ROUTED_SNAPSHOT_OPTION_KEYS);
3028
}

‎src/commands/capture/snapshot.ts‎

Lines changed: 7 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,11 @@
11
import { PUBLIC_COMMANDS } from '@agent-device/command-registry/catalog';
22
import { SNAPSHOT_BACKEND_CAPABILITIES } from '@agent-device/capture-kit/snapshot-quality-backend-capabilities';
3+
import {
4+
SNAPSHOT_COMMAND_OPTION_KEYS,
5+
snapshotOptionsFromFlags,
6+
} from '@agent-device/kernel/snapshot';
37
import { SNAPSHOT_FLAGS } from '../cli-grammar/flag-groups.ts';
4-
import { booleanField, integerField, stringField } from '../command-input.ts';
8+
import { booleanField, integerField, optionField, stringField } from '../command-input.ts';
59
import {
610
commonInputFromFlags,
711
direct,
@@ -32,9 +36,7 @@ const snapshotCommandMetadata = defineFieldCommandMetadata(
3236
depth: integerField(),
3337
scope: stringField(),
3438
raw: booleanField(),
35-
customActions: booleanField(
36-
'Name the affordances an element merged away (iOS UIAccessibilityCustomAction, React Native accessibilityActions) — a card whose reply/options controls are not separate elements still lists them here. The names are for PLANNING, not invocation: there is no API to trigger them, so reach the affordance through the element detail screen, through the same control exposed as a labeled element elsewhere, or by coordinates from its rect. iOS simulator only; costs one accessibility round trip per merged element.',
37-
),
39+
customActions: optionField('snapshotCustomActions'),
3840
forceFull: booleanField(),
3941
timeoutMs: integerField('Maximum wall-clock time for the snapshot command.'),
4042
// #1271 stage 2: `snapshot` is observation-only, so a repair-armed heal
@@ -64,12 +66,7 @@ const snapshotCliSchema = {
6466
export const snapshotCliReader: CliReader = (_positionals, flags) => ({
6567
...commonInputFromFlags(flags),
6668
...observationRecordInputFromFlags(flags),
67-
interactiveOnly: flags.snapshotInteractiveOnly,
68-
depth: flags.snapshotDepth,
69-
scope: flags.snapshotScope,
70-
raw: flags.snapshotRaw,
71-
customActions: flags.snapshotCustomActions,
72-
forceFull: flags.snapshotForceFull,
69+
...snapshotOptionsFromFlags(flags, SNAPSHOT_COMMAND_OPTION_KEYS),
7370
timeoutMs: flags.timeoutMs,
7471
});
7572

‎src/commands/cli-grammar/flag-definitions-action.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -280,6 +280,8 @@ export const ACTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
280280
usageLabel: '--foreground',
281281
usageDescription:
282282
'open: keep normal app/device selection and return an initial snapshot; without an app, resolve the sole running app on the sole booted iOS simulator',
283+
inputDescription:
284+
'Include an initial interactive snapshot in a fresh open response. With no app argument, discover the sole running app on the sole booted iOS simulator; ambiguous environments fail closed.',
283285
},
284286
{
285287
key: 'restart',

‎src/commands/cli-grammar/flag-definitions-workflow.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -206,6 +206,8 @@ export const WORKFLOW_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
206206
usageLabel: '--actions',
207207
usageDescription:
208208
'Snapshot: name the affordances merged inside an element (iOS sim); not directly invokable — reach them via the detail screen, labeled children, or coordinates',
209+
inputDescription:
210+
'Name the affordances an element merged away (iOS UIAccessibilityCustomAction, React Native accessibilityActions) — a card whose reply/options controls are not separate elements still lists them here. The names are for PLANNING, not invocation: there is no API to trigger them, so reach the affordance through the element detail screen, through the same control exposed as a labeled element elsewhere, or by coordinates from its rect. iOS simulator only; costs one accessibility round trip per merged element.',
209211
},
210212
{
211213
key: 'snapshotForceFull',

‎src/commands/cli-grammar/flag-registry.ts‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ import { ACTION_FLAG_DEFINITIONS } from './flag-definitions-action.ts';
22
import { CONNECTION_FLAG_DEFINITIONS } from './flag-definitions-connection.ts';
33
import { TARGET_FLAG_DEFINITIONS } from './flag-definitions-target.ts';
44
import { WORKFLOW_FLAG_DEFINITIONS } from './flag-definitions-workflow.ts';
5-
import type { FlagDefinition } from './flag-types.ts';
5+
import type { FlagDefinition, FlagKey } from './flag-types.ts';
66

77
const FLAG_DEFINITIONS: readonly FlagDefinition[] = [
88
...CONNECTION_FLAG_DEFINITIONS,
@@ -23,3 +23,12 @@ export function getFlagDefinition(token: string): FlagDefinition | undefined {
2323
export function getFlagDefinitions(): readonly FlagDefinition[] {
2424
return FLAG_DEFINITIONS;
2525
}
26+
27+
/**
28+
* The declarations for one flag key. A key can hold more than one when its CLI
29+
* spelling is a `setValue` pair (`--record` / `--no-record`), so the caller
30+
* decides which facet it needs.
31+
*/
32+
export function getFlagDefinitionsForKey(key: FlagKey): readonly FlagDefinition[] {
33+
return FLAG_DEFINITIONS.filter((definition) => definition.key === key);
34+
}

0 commit comments

Comments
 (0)