Skip to content

Commit d23346c

Browse files
authored
refactor(cli): derive the common flag readers from the common-field table (#2292)
* 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). * fix(cli): require a typed flagKey wherever a common row joins flagIn Reviewer findings on the common-flag-reader refactor (9074367): - P2: commonFlagProjection cast flags to Record<string, unknown> and fell back to `field.flagKey ?? key`, so a row could declare `flagIn` with a key that is not a CliFlags property at all (cwd, debug) and compile cleanly while reading undefined forever. CommonInputFieldSpec now requires `flagKey: keyof CliFlags` whenever a row declares `flagIn`; the cast and fallback are gone and commonFlagProjection reads `flags[field.flagKey]` directly. Verified red/green: temporarily adding `flagKey: 'cwd'` made tsc reject the table; reverted after confirming. - P2: comments in common.ts and common-input-fields.ts claimed the table made a dropped common key "impossible" / that flagIn "rides structurally". A new common row that omits flagIn still silently joins neither projection, uncaught by any compiler check -- the flagKey fix narrows the failure mode, it doesn't close it. Reworded both comments to say what the table actually guarantees. - P3: common.test.ts's ALL_COMMON_FLAGS fixture left daemonBaseUrl, daemonAuthToken, tenant, runId, and leaseId unset, so a row wrongly gaining `flagIn: ['input']` for one of them would still pass -- compactRecord drops the unset value either way. Added NON_PROJECTED_COMMON_FLAGS with concrete values for those keys so such a row now surfaces as an extra key. Verified red/green: temporarily adding `flagIn: ['input']` to daemonBaseUrl failed the test; reverted after confirming. - P3: flag-groups.ts's comment said the common-input-fields table declares only envFlagKeys; it now also declares flagKey/flagIn. Amended to name both columns. Deferred one P3 (selectionOptionsFromFlags's cast to SelectionOptions) with a note in .tmp/common-readers-pr-body.md -- fixing it would import cli-grammar/types.ts back into common-input-fields.ts, reversing the documented one-way dependency for a cast the characterization test already pins. No layering, fallow, or gate-manifest surface touched, so no separate chore(gates) commit. Checks: pnpm vitest run --project unit-core src/commands (575 tests, green) and pnpm check:quick (lint + typecheck), both clean.
1 parent 09c1cae commit d23346c

4 files changed

Lines changed: 213 additions & 59 deletions

File tree

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
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+
// Common-input-fields.ts rows that read a real `CliFlags` key but deliberately join neither
27+
// `flagIn` projection today (operator/env-sourced). Setting these too, on top of
28+
// `ALL_COMMON_FLAGS`, means a row that wrongly gained `flagIn: ['input']` would surface a
29+
// concrete value here rather than being silently dropped by `commonInputFromFlags`'s
30+
// `compactRecord` — over-inclusion `ALL_COMMON_FLAGS` alone cannot catch, since an unset flag
31+
// reads as `undefined` and gets compacted away either way.
32+
const NON_PROJECTED_COMMON_FLAGS: Partial<CliFlags> = {
33+
daemonBaseUrl: 'https://daemon.example',
34+
daemonAuthToken: 'token-value',
35+
tenant: 'tenant-value',
36+
runId: 'run-value',
37+
leaseId: 'lease-value',
38+
};
39+
40+
describe('commonInputFromFlags', () => {
41+
test('projects every common flag into the reader-input shape', () => {
42+
expect(
43+
commonInputFromFlags(flags({ ...ALL_COMMON_FLAGS, ...NON_PROJECTED_COMMON_FLAGS })),
44+
).toStrictEqual({
45+
noRecord: true,
46+
session: 'my-session',
47+
platform: 'ios',
48+
deviceTarget: 'mobile',
49+
device: 'iPhone 15',
50+
udid: 'ABCD-1234',
51+
serial: 'emulator-5554',
52+
iosSimulatorDeviceSet: '/tmp/device-set',
53+
iosXctestrunFile: '/tmp/run.xctestrun',
54+
iosXctestDerivedDataPath: '/tmp/derived-data',
55+
iosXctestEnvDir: '/tmp/env-dir',
56+
androidDeviceAllowlist: 'emulator-5554,emulator-5556',
57+
});
58+
});
59+
60+
test('drops every key when no common flag is set', () => {
61+
expect(commonInputFromFlags(flags())).toStrictEqual({});
62+
});
63+
});
64+
65+
describe('selectionOptionsFromFlags', () => {
66+
test('projects the selection-options subset, keeping the raw target spelling', () => {
67+
expect(
68+
selectionOptionsFromFlags(flags({ ...ALL_COMMON_FLAGS, ...NON_PROJECTED_COMMON_FLAGS })),
69+
).toStrictEqual({
70+
noRecord: true,
71+
platform: 'ios',
72+
target: 'mobile',
73+
device: 'iPhone 15',
74+
udid: 'ABCD-1234',
75+
serial: 'emulator-5554',
76+
iosSimulatorDeviceSet: '/tmp/device-set',
77+
androidDeviceAllowlist: 'emulator-5554,emulator-5556',
78+
});
79+
});
80+
81+
test('keeps every key present (undefined, not dropped) when no common flag is set', () => {
82+
expect(selectionOptionsFromFlags(flags())).toStrictEqual({
83+
noRecord: undefined,
84+
platform: undefined,
85+
target: undefined,
86+
device: undefined,
87+
udid: undefined,
88+
serial: undefined,
89+
iosSimulatorDeviceSet: undefined,
90+
androidDeviceAllowlist: undefined,
91+
});
92+
});
93+
});

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

Lines changed: 30 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,28 @@ 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). One row now declares membership for
69+
* both projections instead of two hand-written lists to keep in sync; the
70+
* `flagKey` a row binds to is checked against `CliFlags` at compile time, but
71+
* a *new* common row that omits `flagIn` still joins neither projection
72+
* without a compile error — the #1304/#1305 failure mode is narrowed, not
73+
* made impossible.
74+
*
75+
* `--record` deliberately does NOT join `flagIn`: it is scoped to the
76+
* observation-only commands the repair-segment exclusion can drop (ADR 0012
77+
* decision 6 amendment), so it stays on the narrow
78+
* `observationRecordInputFromFlags` seam below.
79+
*/
5980
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-
});
81+
return compactRecord(commonFlagProjection(flags, 'input'));
8782
}
8883

8984
/**
@@ -101,25 +96,16 @@ export function observationRecordInputFromFlags(flags: CliFlags): Record<string,
10196
}
10297

10398
/**
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).
99+
* The client-options shape for readers that construct a typed Options object
100+
* directly (`is`/`find`/`wait`/`settings`): every common row that lists
101+
* `selection` in `flagIn`, keyed by `clientKey ?? key` (so `deviceTarget`
102+
* comes out as `target`, matching `commonToClientOptions`'s renaming). This is
103+
* a different projection from `commonInputFromFlags` above, not a duplicate —
104+
* unlike that one it is not compacted, so an unset common flag still appears
105+
* with an `undefined` value.
111106
*/
112107
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-
};
108+
return commonFlagProjection(flags, 'selection') as SelectionOptions;
123109
}
124110

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

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

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -53,8 +53,11 @@ export const REPLAY_FLAGS = flagKeys('replayUpdate', 'replayEnv');
5353
// structured command input, while the table's `cwd` and `debug` are not flags
5454
// and its `deviceTarget` row is spelled `target` here. Deriving this list from
5555
// that table would mean 25 rows carrying no schema, reader, or projection, so
56-
// the two stay separate; the table declares only `envFlagKeys`, where a flag key
57-
// names the environment variable an operator-owned input comes from.
56+
// the two stay separate; the table declares `envFlagKeys` (which environment
57+
// variable an operator-owned input comes from) and `flagKey`/`flagIn` (which
58+
// `CliFlags` property a row reads and which reader projections it joins) —
59+
// this list stays the parser-side axis, naming every flag the CLI grammar
60+
// accepts regardless of whether a common-input-fields row reads it at all.
5861
export const COMMON_COMMAND_SUPPORTED_FLAG_KEYS = flagKeys(
5962
'remoteConfig',
6063
'stateDir',

0 commit comments

Comments
 (0)