Skip to content

Commit 9074367

Browse files
committed
refactor(cli): derive the common flag readers from the common-field table
commonInputFromFlags and selectionOptionsFromFlags in src/commands/cli-grammar/common.ts each hand-restated the common input key list as object literals. A key added to the common-field table in commands/common-input-fields.ts (the schema/read/clientKey/audience source of truth) had no structural link to either flag reader, so keeping a new key flowing through the CLI depended on remembering to touch both literals by hand (the failure mode #1304/#1305 hit for --no-record). Add a flagKey/flagIn column to CommonInputFieldSpec: flagKey names the CliFlags property when its spelling differs from the row (only deviceTarget, which reads flags.target), and flagIn lists which of the two flag-derived projections ('input', 'selection') the row joins. commonFlagProjection(flags, projection) walks the table once and reuses the existing clientKey renaming (deviceTarget -> target) for the 'selection' projection, matching commonToClientOptions's existing convention. commonInputFromFlags and selectionOptionsFromFlags become thin wrappers over that projection; COMMON_COMMAND_SUPPORTED_FLAG_KEYS in flag-groups.ts is untouched, per its own documented reason for staying separate. Added src/commands/cli-grammar/common.test.ts as a characterization test before touching the implementation: it feeds a CliFlags fixture with every common flag set, and one with none set, and asserts the literal objects both functions return. It passed unmodified against both the old hand-written implementation and the new table-derived one, proving the projections are byte-identical. Validation: pnpm vitest run --project unit-core src/commands (575 tests, all green); pnpm check:quick (lint + typecheck) clean; pnpm check:layering clean (cli-grammar/common.ts importing commands/common-input-fields.ts is an intra-commands-zone import, not core/daemon reaching into commands, so R2 commands-floor does not apply).
1 parent fa06c8c commit 9074367

3 files changed

Lines changed: 162 additions & 56 deletions

File tree

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
import { describe, expect, test } from 'vitest';
2+
import type { CliFlags } from '@agent-device/contracts/command';
3+
import { commonInputFromFlags, selectionOptionsFromFlags } from './common.ts';
4+
5+
function flags(overrides: Partial<CliFlags> = {}): CliFlags {
6+
return overrides as CliFlags;
7+
}
8+
9+
// Every flag either reader function is documented to read (see the `commonInputFromFlags` and
10+
// `selectionOptionsFromFlags` doc comments in ./common.ts).
11+
const ALL_COMMON_FLAGS: Partial<CliFlags> = {
12+
noRecord: true,
13+
session: 'my-session',
14+
platform: 'ios',
15+
target: 'mobile',
16+
device: 'iPhone 15',
17+
udid: 'ABCD-1234',
18+
serial: 'emulator-5554',
19+
iosSimulatorDeviceSet: '/tmp/device-set',
20+
iosXctestrunFile: '/tmp/run.xctestrun',
21+
iosXctestDerivedDataPath: '/tmp/derived-data',
22+
iosXctestEnvDir: '/tmp/env-dir',
23+
androidDeviceAllowlist: 'emulator-5554,emulator-5556',
24+
};
25+
26+
describe('commonInputFromFlags', () => {
27+
test('projects every common flag into the reader-input shape', () => {
28+
expect(commonInputFromFlags(flags(ALL_COMMON_FLAGS))).toStrictEqual({
29+
noRecord: true,
30+
session: 'my-session',
31+
platform: 'ios',
32+
deviceTarget: 'mobile',
33+
device: 'iPhone 15',
34+
udid: 'ABCD-1234',
35+
serial: 'emulator-5554',
36+
iosSimulatorDeviceSet: '/tmp/device-set',
37+
iosXctestrunFile: '/tmp/run.xctestrun',
38+
iosXctestDerivedDataPath: '/tmp/derived-data',
39+
iosXctestEnvDir: '/tmp/env-dir',
40+
androidDeviceAllowlist: 'emulator-5554,emulator-5556',
41+
});
42+
});
43+
44+
test('drops every key when no common flag is set', () => {
45+
expect(commonInputFromFlags(flags())).toStrictEqual({});
46+
});
47+
});
48+
49+
describe('selectionOptionsFromFlags', () => {
50+
test('projects the selection-options subset, keeping the raw target spelling', () => {
51+
expect(selectionOptionsFromFlags(flags(ALL_COMMON_FLAGS))).toStrictEqual({
52+
noRecord: true,
53+
platform: 'ios',
54+
target: 'mobile',
55+
device: 'iPhone 15',
56+
udid: 'ABCD-1234',
57+
serial: 'emulator-5554',
58+
iosSimulatorDeviceSet: '/tmp/device-set',
59+
androidDeviceAllowlist: 'emulator-5554,emulator-5556',
60+
});
61+
});
62+
63+
test('keeps every key present (undefined, not dropped) when no common flag is set', () => {
64+
expect(selectionOptionsFromFlags(flags())).toStrictEqual({
65+
noRecord: undefined,
66+
platform: undefined,
67+
target: undefined,
68+
device: undefined,
69+
udid: undefined,
70+
serial: undefined,
71+
iosSimulatorDeviceSet: undefined,
72+
androidDeviceAllowlist: undefined,
73+
});
74+
});
75+
});

‎src/commands/cli-grammar/common.ts‎

Lines changed: 26 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ import {
1111
SELECTOR_EXPRESSION_REQUIRED_MESSAGE,
1212
splitSelectorFromArgs,
1313
} from '@agent-device/selectors';
14+
import { commonFlagProjection } from '../common-input-fields.ts';
1415
import type { SelectorSnapshotInput } from '../command-input.ts';
1516
import { compactRecord } from '../input-readers.ts';
1617
import type {
@@ -56,34 +57,24 @@ function readDeviceTarget(value: unknown): InternalRequestOptions['target'] | un
5657
return value === 'mobile' || value === 'tv' || value === 'desktop' ? value : undefined;
5758
}
5859

60+
/**
61+
* The reader-input shape: every common key whose `commands/common-input-fields.ts`
62+
* row lists `input` in `flagIn`, keyed by its own row name (`deviceTarget`, not
63+
* the CLI's `--target` spelling). `--no-record` is one such row
64+
* (`COMMON_COMMAND_SUPPORTED_FLAG_KEYS`) — it is accepted on, and meaningful
65+
* for, every recordable command, and joining the table's `flagIn` is what
66+
* makes it ride this projection and `selectionOptionsFromFlags` below without
67+
* either reader restating it (#1304/#1305 fixed only the reader layer, so the
68+
* flag still never reached the daemon; the table now makes that drop
69+
* impossible rather than merely documented against).
70+
*
71+
* `--record` deliberately does NOT join `flagIn`: it is scoped to the
72+
* observation-only commands the repair-segment exclusion can drop (ADR 0012
73+
* decision 6 amendment), so it stays on the narrow
74+
* `observationRecordInputFromFlags` seam below.
75+
*/
5976
export function commonInputFromFlags(flags: CliFlags): Record<string, unknown> {
60-
return compactRecord({
61-
// `--no-record` is a COMMON flag (`COMMON_COMMAND_SUPPORTED_FLAG_KEYS`): it
62-
// is accepted on, and meaningful for, every recordable command. It rides
63-
// the common seam every reader already spreads, so a reader cannot forget
64-
// it and a new reader inherits it for free. The three seams it must survive
65-
// are this one, `readCommonInput`, and `commonToClientOptions`
66-
// (`commands/common-input-fields.ts`) — a drop at any one of them silently
67-
// disables the flag (#1304/#1305 fixed only the reader layer, so the flag
68-
// still never reached the daemon).
69-
//
70-
// `--record` deliberately does NOT ride here: it is scoped to the
71-
// observation-only commands the repair-segment exclusion can drop
72-
// (ADR 0012 decision 6 amendment), so it stays on the narrow
73-
// `observationRecordInputFromFlags` seam below.
74-
noRecord: flags.noRecord,
75-
session: flags.session,
76-
platform: flags.platform,
77-
deviceTarget: flags.target,
78-
device: flags.device,
79-
udid: flags.udid,
80-
serial: flags.serial,
81-
iosSimulatorDeviceSet: flags.iosSimulatorDeviceSet,
82-
iosXctestrunFile: flags.iosXctestrunFile,
83-
iosXctestDerivedDataPath: flags.iosXctestDerivedDataPath,
84-
iosXctestEnvDir: flags.iosXctestEnvDir,
85-
androidDeviceAllowlist: flags.androidDeviceAllowlist,
86-
});
77+
return compactRecord(commonFlagProjection(flags, 'input'));
8778
}
8879

8980
/**
@@ -101,25 +92,16 @@ export function observationRecordInputFromFlags(flags: CliFlags): Record<string,
10192
}
10293

10394
/**
104-
* The reader layer has TWO parallel common seams, not one: this builds the
105-
* client-options shape (`target`) for readers that construct a typed Options
106-
* object directly (`is`/`find`/`wait`/`settings`), while `commonInputFromFlags`
107-
* above builds the reader-input shape (`deviceTarget`). They are different
108-
* projections, not duplicates — so `--no-record` has to ride BOTH or the
109-
* readers using this one silently drop it (which is what #1304/#1305's
110-
* per-reader helper was papering over).
95+
* The client-options shape for readers that construct a typed Options object
96+
* directly (`is`/`find`/`wait`/`settings`): every common row that lists
97+
* `selection` in `flagIn`, keyed by `clientKey ?? key` (so `deviceTarget`
98+
* comes out as `target`, matching `commonToClientOptions`'s renaming). This is
99+
* a different projection from `commonInputFromFlags` above, not a duplicate —
100+
* unlike that one it is not compacted, so an unset common flag still appears
101+
* with an `undefined` value.
111102
*/
112103
export function selectionOptionsFromFlags(flags: CliFlags): SelectionOptions {
113-
return {
114-
noRecord: flags.noRecord,
115-
platform: flags.platform,
116-
target: flags.target,
117-
device: flags.device,
118-
udid: flags.udid,
119-
serial: flags.serial,
120-
iosSimulatorDeviceSet: flags.iosSimulatorDeviceSet,
121-
androidDeviceAllowlist: flags.androidDeviceAllowlist,
122-
};
104+
return commonFlagProjection(flags, 'selection') as SelectionOptions;
123105
}
124106

125107
export function selectorSnapshotInputFromFlags(flags: CliFlags): Record<string, unknown> {

‎src/commands/common-input-fields.ts‎

Lines changed: 61 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import type { CliFlags } from '@agent-device/contracts/command';
12
import type {
23
AgentDeviceRequestOverrides,
34
AgentDeviceSelectionOptions,
@@ -33,11 +34,20 @@ export type CommonCommandInput = Pick<
3334

3435
export type CommonInputReadOptions = { readTargetAlias?: boolean };
3536

37+
/**
38+
* `cli-grammar/common.ts`'s two flag-derived projections a row can join:
39+
* `input` is the reader-input shape (`commonInputFromFlags`, compacted), `selection` is the
40+
* client-options shape kept by `is`/`find`/`wait`/`settings` (`selectionOptionsFromFlags`,
41+
* not compacted). A row absent from both is never read off `CliFlags` at all.
42+
*/
43+
export type CommonFlagProjection = 'input' | 'selection';
44+
3645
/**
3746
* One row per input key every command accepts. The JSON schema, the readers,
38-
* the client-options projection, and the model-facing audience boundary are all
39-
* derived from this table, so adding or reclassifying a common key is a one-row
40-
* edit rather than a matching edit in four parallel enumerations.
47+
* the client-options projection, the model-facing audience boundary, and the two
48+
* flag-derived projections below are all derived from this table, so adding or
49+
* reclassifying a common key is a one-row edit rather than a matching edit across
50+
* parallel enumerations.
4151
*/
4252
type CommonInputFieldSpec = {
4353
/** Advertised property. Absent for a key each command schema carries itself (`noRecord`). */
@@ -48,6 +58,10 @@ type CommonInputFieldSpec = {
4858
clientKey?: string;
4959
/** Who may write the key. Absent means the model — see `input-audience.ts`. */
5060
audience?: InputAudience;
61+
/** The `CliFlags` property this key reads, when its spelling differs (e.g. `deviceTarget` reads `flags.target`). */
62+
flagKey?: keyof CliFlags;
63+
/** Which of `cli-grammar/common.ts`'s flag-derived projections include this row. Absent joins neither. */
64+
flagIn?: readonly CommonFlagProjection[];
5165
};
5266

5367
/**
@@ -64,6 +78,7 @@ const COMMON_INPUT_FIELDS = {
6478
session: {
6579
schema: { type: 'string', description: 'Agent-device session name.' },
6680
read: (record) => optionalString(record, 'session'),
81+
flagIn: ['input'],
6782
},
6883
platform: {
6984
schema: {
@@ -72,6 +87,7 @@ const COMMON_INPUT_FIELDS = {
7287
description: 'Platform selector used to resolve a device.',
7388
},
7489
read: (record) => optionalEnum(record, 'platform', PLATFORM_SELECTORS),
90+
flagIn: ['input', 'selection'],
7591
},
7692
deviceTarget: {
7793
schema: {
@@ -81,6 +97,8 @@ const COMMON_INPUT_FIELDS = {
8197
},
8298
read: readDeviceTarget,
8399
clientKey: 'target',
100+
flagKey: 'target',
101+
flagIn: ['input', 'selection'],
84102
},
85103
target: {
86104
// Read through `deviceTarget` above, which reconciles the two spellings.
@@ -97,6 +115,7 @@ const COMMON_INPUT_FIELDS = {
97115
description: 'Device name selector (a UDID belongs in udid, a serial in serial).',
98116
},
99117
read: (record) => optionalString(record, 'device'),
118+
flagIn: ['input', 'selection'],
100119
},
101120
udid: {
102121
schema: {
@@ -105,13 +124,15 @@ const COMMON_INPUT_FIELDS = {
105124
'Apple device or simulator UDID; the selector that pins one device when several share a name.',
106125
},
107126
read: (record) => optionalString(record, 'udid'),
127+
flagIn: ['input', 'selection'],
108128
},
109129
serial: {
110130
schema: {
111131
type: 'string',
112132
description: 'Android, HarmonyOS, or Vega VVD serial selector.',
113133
},
114134
read: (record) => optionalString(record, 'serial'),
135+
flagIn: ['input', 'selection'],
115136
},
116137
iosSimulatorDeviceSet: {
117138
schema: {
@@ -120,6 +141,7 @@ const COMMON_INPUT_FIELDS = {
120141
},
121142
read: (record) => optionalString(record, 'iosSimulatorDeviceSet'),
122143
audience: operatorAudience({ envFlagKeys: [], operatorConfig: true }),
144+
flagIn: ['input', 'selection'],
123145
},
124146
iosXctestrunFile: {
125147
schema: {
@@ -128,6 +150,7 @@ const COMMON_INPUT_FIELDS = {
128150
},
129151
read: (record) => optionalString(record, 'iosXctestrunFile'),
130152
audience: ENV_OR_OPERATOR_CONFIG,
153+
flagIn: ['input'],
131154
},
132155
iosXctestDerivedDataPath: {
133156
schema: {
@@ -136,6 +159,7 @@ const COMMON_INPUT_FIELDS = {
136159
},
137160
read: (record) => optionalString(record, 'iosXctestDerivedDataPath'),
138161
audience: ENV_OR_OPERATOR_CONFIG,
162+
flagIn: ['input'],
139163
},
140164
iosXctestEnvDir: {
141165
schema: {
@@ -144,20 +168,25 @@ const COMMON_INPUT_FIELDS = {
144168
},
145169
read: (record) => optionalString(record, 'iosXctestEnvDir'),
146170
audience: ENV_OR_OPERATOR_CONFIG,
171+
flagIn: ['input'],
147172
},
148173
androidDeviceAllowlist: {
149174
schema: {
150175
type: 'string',
151176
description: 'Android serial allowlist used for device resolution.',
152177
},
153178
read: (record) => optionalString(record, 'androidDeviceAllowlist'),
179+
flagIn: ['input', 'selection'],
154180
},
155181
noRecord: {
156-
// Seam 2 of 3 for `--no-record` (see `commonInputFromFlags`). `readFieldInput`
157-
// keeps ONLY declared metadata fields plus this common input, so a flag
158-
// absent here is filtered out of every field-based command's input before
159-
// the client ever sees it.
182+
// `readFieldInput` keeps ONLY declared metadata fields plus this common
183+
// input, so a flag absent here is filtered out of every field-based
184+
// command's input before the client ever sees it. `flagIn` below is the
185+
// only seam that used to be hand-maintained (#1304/#1305, #1311, #1313);
186+
// it now rides both flag-derived projections structurally, the same as
187+
// every other row.
160188
read: (record) => optionalBoolean(record, 'noRecord'),
189+
flagIn: ['input', 'selection'],
161190
},
162191
daemonBaseUrl: {
163192
schema: { type: 'string', description: 'Remote daemon base URL.' },
@@ -227,16 +256,36 @@ export function commonToClientOptions(
227256
const options: Record<string, unknown> = {};
228257
for (const [key, field] of COMMON_INPUT_ROWS) {
229258
if (!field.read) continue;
230-
// Seam 3 of 3 for `--no-record` (see `commonInputFromFlags`). Every
231-
// `to*Options` projection (`toPressOptions`, `toGetOptions`, ...) rebuilds
232-
// the client options object from this helper plus its own named fields, so
233-
// a key absent here is dropped even when the reader forwarded it and
234-
// `readCommonInput` kept it.
259+
// Every `to*Options` projection (`toPressOptions`, `toGetOptions`, ...)
260+
// rebuilds the client options object from this helper plus its own named
261+
// fields, so a key absent from the table is dropped here even when the
262+
// reader forwarded it and `readCommonInput` kept it (#1304/#1305).
235263
options[field.clientKey ?? key] = input[key as keyof CommonCommandInput];
236264
}
237265
return compactRecord(options) as AgentDeviceRequestOverrides & AgentDeviceSelectionOptions;
238266
}
239267

268+
/**
269+
* `cli-grammar/common.ts`'s two `CliFlags` readers (`commonInputFromFlags`,
270+
* `selectionOptionsFromFlags`) project this same table instead of restating
271+
* their key lists: a row joins a projection only when `flagIn` names it, and
272+
* its output key is the row key for `input`, or `clientKey ?? key` for
273+
* `selection` — the same renaming `commonToClientOptions` already applies.
274+
*/
275+
export function commonFlagProjection(
276+
flags: CliFlags,
277+
projection: CommonFlagProjection,
278+
): Record<string, unknown> {
279+
const record = flags as unknown as Record<string, unknown>;
280+
const options: Record<string, unknown> = {};
281+
for (const [key, field] of COMMON_INPUT_ROWS) {
282+
if (!field.flagIn?.includes(projection)) continue;
283+
const outputKey = projection === 'selection' ? (field.clientKey ?? key) : key;
284+
options[outputKey] = record[field.flagKey ?? key];
285+
}
286+
return options;
287+
}
288+
240289
function readDeviceTarget(
241290
record: Record<string, unknown>,
242291
options: CommonInputReadOptions,

0 commit comments

Comments
 (0)