Skip to content

Commit 600cda7

Browse files
committed
fix(settings): address review on the explicit-app scope (#3179)
- correct the app-not-consumed hint to `--app <app>`: a trailing app id parses as the permission mode - stop claiming app-scoped settings coverage in the integration progress row - name the written flag token and refuse a repeated --app on a replay script line - refuse clear-app-state naming two different apps instead of dropping one - let the CLI admit --app through allowedFlags alone and keep settingsAppScope the one decision - gate the permission diagnostic's appBundleId on an app-scoped target - use isIosFamily in the scope table and share SettingsAppRefusal between the refusal builders - correct the client docs to say a macOS named app is refused and point at settingsAppScope - pin the state-normalization case on the iOS location row Refs #3179
1 parent 5b95d88 commit 600cda7

11 files changed

Lines changed: 107 additions & 126 deletions

File tree

‎packages/ad-script/src/internal/__tests__/script-utils.test.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,3 +45,9 @@ test('a settings --app round-trips through a script line', () => {
4545
test('a settings line with a valueless --app is refused instead of replaying app-less', () => {
4646
expect(() => parseReplayScriptDetailed('settings location on --app')).toThrow(/--app/);
4747
});
48+
49+
test('a settings line naming --app twice is refused instead of keeping the last one', () => {
50+
expect(() =>
51+
parseReplayScriptDetailed('settings permission grant camera --app com.a --app com.b'),
52+
).toThrow(/twice/);
53+
});

‎packages/ad-script/src/internal/script.ts‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -424,7 +424,16 @@ function parseReplayScriptLine(line: string): SessionAction | null {
424424
if (token === '--app' || token === '--target-app') {
425425
const value = args[index + 1];
426426
if (value === undefined) {
427-
throw new AppError('INVALID_ARGS', `Replay script line "${trimmed}" has no --app value.`);
427+
throw new AppError(
428+
'INVALID_ARGS',
429+
`Replay script line "${trimmed}" has no ${token} value.`,
430+
);
431+
}
432+
if (action.flags.targetApp !== undefined) {
433+
throw new AppError(
434+
'INVALID_ARGS',
435+
`Replay script line "${trimmed}" names ${token} twice.`,
436+
);
428437
}
429438
action.flags.targetApp = value;
430439
index += 1;

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

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ export type SettingsUpdateOptions =
3636
* On Apple simulators `on`/`off` grants or revokes the app's location permission, so this leg
3737
* takes the same explicit `app` as `permission` and defaults to the session app. On Android the
3838
* toggle writes the global `location_mode` and consumes no app, so naming one there is refused
39-
* rather than dropped; `settingsAppConsumesApp` is the declaration.
39+
* rather than dropped; `settingsAppScope` is the declaration.
4040
*/
4141
| (DeviceCommandBaseOptions & {
4242
setting: 'location';
@@ -82,7 +82,8 @@ export type SettingsUpdateOptions =
8282
/**
8383
* The app the permission changes, by bundle id or package name. Without it the app bound to
8484
* the session is used; with it no app has to be running or open, because `simctl privacy` and
85-
* Android's `pm` need only the id. macOS permissions are host-level and ignore it.
85+
* Android's `pm` need only the id. macOS permissions are host-level, so naming an app there is
86+
* refused rather than ignored.
8687
*/
8788
app?: string;
8889
});

‎packages/contracts/src/settings.test.ts‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -390,8 +390,11 @@ describe('settings app scope (#3179)', () => {
390390
);
391391

392392
test('normalizes case and padding on both the setting and the state', () => {
393-
expect(settingsAppScope(iosSimulator, ' Permission ', ' GRANT ')).toBe('app-scoped');
394-
expect(settingsAppScope(android, ' LOCATION ', 'Set')).toBe('device-level');
393+
expect(settingsAppScope(iosSimulator, ' Permission ', ' grant')).toBe('app-scoped');
394+
// Only the state's normalized `set` moves an iOS on/off grant to the device-level row, so this
395+
// is the case that fails if the state stops being normalized.
396+
expect(settingsAppScope(iosSimulator, ' LOCATION ', ' SET ')).toBe('device-level');
397+
expect(settingsAppScope(iosSimulator, ' LOCATION ', ' ON ')).toBe('app-scoped');
395398
});
396399
});
397400

@@ -407,7 +410,7 @@ describe('settings app-not-consumed refusal (#3179)', () => {
407410
setting: 'location on',
408411
app: 'com.example.app',
409412
});
410-
expect(refusal.hint).toContain('settings permission grant location com.example.app');
413+
expect(refusal.hint).toContain('settings permission grant location --app com.example.app');
411414
});
412415

413416
test('a nameless app is refused with its own typed reason', () => {

‎packages/contracts/src/settings.ts‎

Lines changed: 17 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { isApplePlatform, isMacOs, type DeviceInfo } from '@agent-device/kernel/device';
1+
import { isIosFamily, isMacOs, type DeviceInfo } from '@agent-device/kernel/device';
22
import { AppError } from '@agent-device/kernel/errors';
33

44
/**
@@ -188,7 +188,7 @@ export function settingsAppScope(
188188
}
189189
if (normalizedSetting === 'location') {
190190
if (state?.trim().toLowerCase() === 'set') return 'device-level';
191-
return isApplePlatform(device.platform) && !isMacOs(device) ? 'app-scoped' : 'device-level';
191+
return isIosFamily(device) ? 'app-scoped' : 'device-level';
192192
}
193193
return 'device-level';
194194
}
@@ -208,13 +208,22 @@ export const SETTINGS_APP_NOT_CONSUMED_REASON = 'setting_app_not_consumed';
208208
*/
209209
export const SETTINGS_APP_NOT_NAMED_REASON = 'setting_app_not_named';
210210

211-
/** The refusal for an `app` that arrived with nothing in it. */
212-
export function settingsAppNotNamedRefusal(app: string): {
211+
/**
212+
* A settings refusal that answers before a device is touched: the code, sentence, typed details,
213+
* and hint as data, so the daemon can answer with it through its own response builder rather than
214+
* by unwrapping an error the CLI would then re-normalize. Every one of them pairs with
215+
* `dispatched: 'no'`, and the `app` the caller named stays in `details` — they asked about that
216+
* bundle id and the answer quotes it back.
217+
*/
218+
export type SettingsAppRefusal = Readonly<{
213219
code: 'INVALID_ARGS';
214220
message: string;
215221
details: Record<string, unknown>;
216222
hint: string;
217-
} {
223+
}>;
224+
225+
/** The refusal for an `app` that arrived with nothing in it. */
226+
export function settingsAppNotNamedRefusal(app: string): SettingsAppRefusal {
218227
return {
219228
code: 'INVALID_ARGS',
220229
message: `settings was given an app with no name in it: "${app}" is not a bundle id or package.`,
@@ -223,22 +232,12 @@ export function settingsAppNotNamedRefusal(app: string): {
223232
};
224233
}
225234

226-
/**
227-
* The refusal a mutation answers with when its target consumes no app: the code, sentence, typed
228-
* details, and hint as data, so the daemon can answer with it through its own response builder
229-
* rather than by unwrapping an error the CLI would then re-normalize. The `app` that named nothing
230-
* stays in `details` — the caller asked about that bundle id and the answer should quote it back.
231-
*/
235+
/** The refusal a mutation answers with when its target consumes no app. */
232236
export function settingsAppNotConsumedRefusal(
233237
setting: string,
234238
state: string | undefined,
235239
app: string,
236-
): {
237-
code: 'INVALID_ARGS';
238-
message: string;
239-
details: Record<string, unknown>;
240-
hint: string;
241-
} {
240+
): SettingsAppRefusal {
242241
const described = state === undefined ? setting : `${setting} ${state}`;
243242
return {
244243
code: 'INVALID_ARGS',
@@ -249,7 +248,7 @@ export function settingsAppNotConsumedRefusal(
249248
setting: described,
250249
app,
251250
},
252-
hint: `Drop the app and run \`settings ${described}\`, or aim it at an app-scoped setting such as \`settings permission grant location ${app}\`.`,
251+
hint: `Drop the app and run \`settings ${described}\`, or aim it at an app-scoped setting such as \`settings permission grant location --app ${app}\`.`,
253252
};
254253
}
255254

‎scripts/integration-progress-model.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -136,7 +136,7 @@ function summarizeProviderScenarioFlagCoverage(files) {
136136
['iosSimulatorDeviceSet', 'iOS simulator-set scoping reaches inventory resolution'],
137137
['androidDeviceAllowlist', 'Android serial allowlist reaches inventory resolution'],
138138
['session', 'named session routing'],
139-
['targetApp', 'doctor app check and app-scoped settings on an app not opened in session'],
139+
['targetApp', 'doctor target app discovery without opening a session'],
140140
['surface', 'macOS app/frontmost/desktop/menubar surfaces'],
141141
['activity', 'Android explicit launch activity'],
142142
['launchConsole', 'iOS simulator launch console capture'],

‎src/cli/parser/__tests__/args-validation.test.ts‎

Lines changed: 8 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -262,44 +262,22 @@ test('invalid range errors are deterministic', () => {
262262
);
263263
});
264264

265-
// #3179: `settings` reads --app, but only for the actions that can consume it.
266-
test('parseArgs accepts --app for the settings actions that consume an app', () => {
265+
// #3179: the CLI admits --app for every settings action and the daemon's scope table decides who
266+
// consumes it, so a device-wide leg still parses and carries the app to that decision.
267+
test('parseArgs accepts --app for every settings action', () => {
267268
const cases = [
268269
['settings', 'permission', 'grant', 'camera', '--app', 'com.example.app'],
269270
['settings', 'permission', 'deny', 'photos', '--app=com.example.app'],
270271
['settings', 'location', 'on', '--app', 'com.example.app'],
272+
['settings', 'location', 'set', '1', '2', '--app', 'com.example.app'],
271273
['settings', 'clear-app-state', '--app', 'com.example.app'],
274+
['settings', 'wifi', 'on', '--app', 'com.example.app'],
275+
['settings', 'appearance', 'dark', '--app', 'com.example.app'],
276+
['settings', 'text-size', 'large', '--app', 'com.example.app'],
277+
['settings', 'reset-keychain', 'clear', '--app', 'com.example.app'],
272278
];
273279
for (const argv of cases) {
274280
const parsed = parseArgs(argv, { strictFlags: true });
275281
assert.equal(parsed.flags.targetApp, 'com.example.app');
276282
}
277283
});
278-
279-
test('parseArgs refuses --app for a settings action that reads none', () => {
280-
const cases: Array<[string[], string]> = [
281-
[['settings', 'wifi', 'on', '--app', 'com.example.app'], 'settings wifi does not read --app'],
282-
[
283-
['settings', 'appearance', 'dark', '--app', 'com.example.app'],
284-
'settings appearance does not read --app',
285-
],
286-
[
287-
['settings', 'text-size', 'large', '--app', 'com.example.app'],
288-
'settings text-size does not read --app',
289-
],
290-
[
291-
['settings', 'reset-keychain', 'clear', '--app', 'com.example.app'],
292-
'settings reset-keychain does not read --app',
293-
],
294-
];
295-
for (const [argv, message] of cases) {
296-
assert.throws(
297-
() => parseArgs(argv, { strictFlags: true }),
298-
(error: unknown) =>
299-
error instanceof AppError &&
300-
error.code === 'INVALID_ARGS' &&
301-
error.message.startsWith(message),
302-
`expected ${argv.join(' ')} to be refused`,
303-
);
304-
}
305-
});

‎src/commands/capture/settings.test.ts‎

Lines changed: 14 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -284,22 +284,28 @@ describe('settings CLI explicit app (#3179)', () => {
284284
expect(settingsDaemonWriter(input).options.targetApp).toBeUndefined();
285285
});
286286

287-
test('lets the clear-app-state positional win over --app and keep riding the positional', () => {
287+
test('uses the clear-app-state positional and drops a duplicate --app', () => {
288288
const input = settingsCliReader(
289-
['clear-app-state', 'com.from.positional'],
290-
appFlags('com.from.flag'),
289+
['clear-app-state', 'com.example.app'],
290+
appFlags('com.example.app'),
291291
);
292292
expect(input).toMatchObject({
293293
setting: 'clear-app-state',
294294
state: 'clear',
295-
app: 'com.from.positional',
295+
app: 'com.example.app',
296296
});
297297
expect(settingsDaemonWriter(input)).toMatchObject({
298-
positionals: ['clear-app-state', 'com.from.positional'],
299-
options: { targetApp: 'com.from.positional' },
298+
positionals: ['clear-app-state', 'com.example.app'],
299+
options: { targetApp: 'com.example.app' },
300300
});
301301
});
302302

303+
test('refuses clear-app-state naming two different apps', () => {
304+
expect(() =>
305+
settingsCliReader(['clear-app-state', 'com.from.positional'], appFlags('com.from.flag')),
306+
).toThrow(/two apps/);
307+
});
308+
303309
test('falls back to --app for clear-app-state when no positional names one', () => {
304310
const input = settingsCliReader(['clear-app-state', 'clear'], appFlags('com.example.app'));
305311
expect(input).toMatchObject({ app: 'com.example.app' });
@@ -314,11 +320,10 @@ describe('settings CLI explicit app (#3179)', () => {
314320
expect(settingsDaemonWriter(input).options.targetApp).toBe('com.example.app');
315321
});
316322

317-
test('advertises --app in its synopsis and refuses it for a setting that reads none', () => {
323+
test('advertises --app and leaves every action to the daemon-side scope table', () => {
318324
const schema = settingsCommandFacet.cliSchema;
319325
expect(schema.allowedFlags).toEqual(['targetApp']);
320-
expect(schema.flagsByAction?.wifi).toEqual([]);
321-
expect(schema.flagsByAction?.permission).toEqual(['targetApp']);
326+
expect(schema.flagsByAction).toBeUndefined();
322327
});
323328

324329
test('keeps the app-aware form in the command detail', () => {

‎src/commands/capture/settings.ts‎

Lines changed: 23 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -53,42 +53,16 @@ const settingsCommandMetadata = defineFieldCommandMetadata(
5353
);
5454

5555
/**
56-
* Which `settings` action reads which option.
57-
*
58-
* `app` is the only action-scoped option this command has, and the row list is what makes the
59-
* refusal real: `settings wifi on --app com.example.app` would otherwise look like an app-scoped
60-
* Wi-Fi toggle and then have the name silently dropped by the daemon. Every other setting reads no
61-
* option, so its row is empty; `clear-app-state` reads `app` through its positional.
62-
*
63-
* The table keys on the action alone, so `location` admits `--app` for both `on|off` (an Apple
64-
* grant) and `set` (which moves the device). Only the target decides that one, so the daemon's
65-
* scope table is the backstop and the reader carries the app to it instead of guessing per branch.
56+
* `--app` is admitted for every `settings` action and consumed by only some of them: the CLI is not
57+
* the place that decides which, because that answer belongs to the target. `settingsAppScope` in
58+
* `@agent-device/contracts/settings` is the one table, and the daemon applies it to refuse an app a
59+
* device-wide setting cannot consume before it touches anything.
6660
*/
67-
const SETTINGS_FLAGS_BY_ACTION: Readonly<Record<string, readonly FlagKey[]>> = {
68-
permission: ['targetApp'],
69-
location: ['targetApp'],
70-
'clear-app-state': ['targetApp'],
71-
wifi: [],
72-
airplane: [],
73-
animations: [],
74-
appearance: [],
75-
'text-size': [],
76-
faceid: [],
77-
touchid: [],
78-
fingerprint: [],
79-
'reset-keychain': [],
80-
};
81-
82-
const SETTINGS_CLI_FLAGS: readonly FlagKey[] = [
83-
...new Set(Object.values(SETTINGS_FLAGS_BY_ACTION).flat()),
84-
];
85-
8661
const settingsCliSchema = {
8762
usageOverride: SETTINGS_USAGE_OVERRIDE,
8863
listUsageOverride: 'settings [area] [options]',
8964
positionalArgs: ['setting', 'state?', 'target?', 'mode?'],
90-
allowedFlags: SETTINGS_CLI_FLAGS,
91-
flagsByAction: SETTINGS_FLAGS_BY_ACTION,
65+
allowedFlags: ['targetApp'] as const satisfies readonly FlagKey[],
9266
flagDescriptionOverrides: {
9367
targetApp:
9468
'Apply an app-scoped change to this bundle id or package without opening it: permission grant|deny|reset, iOS location on|off, clear-app-state. Refused for a setting the target serves device-wide.',
@@ -99,12 +73,9 @@ export const settingsCliReader: CliReader = (positionals, flags) =>
9973
readSettingsOptionsFromPositionals(positionals, flags);
10074

10175
/**
102-
* The `app` the caller named rides `options.targetApp` to the daemon rather than being restated as a
103-
* settings-specific wire key: it is the same "aim this at an app I am not opening" the doctor already
104-
* carries, and `buildFlags` projects that one key onto the request. `--app` arrives on the same key
105-
* from the CLI reader, so both surfaces converge here. It is copied for every setting, including the
106-
* ones that cannot consume one, so the daemon is the single place that decides — and refuses —
107-
* rather than a writer that would have to duplicate the per-target table.
76+
* The `app` the caller named rides `options.targetApp` to the daemon, the same key doctor uses to
77+
* aim a command at an app the session never opened. It is copied for every setting, including the
78+
* ones that cannot consume one, so the daemon is the single place that decides and refuses.
10879
*/
10980
export const settingsDaemonWriter: DaemonWriter = (input) => {
11081
const app = input.app;
@@ -136,9 +107,8 @@ function readSettingsOptionsFromPositionals(
136107
positionals: string[],
137108
flags: CliFlags,
138109
): SettingsUpdateOptions {
139-
// `--app` rides every leg, not only the ones the parser let it through on: the reader is a
140-
// projection and the daemon's scope table is the one decision, so a named app reaches that table
141-
// instead of being dropped here depending on which branch the grammar happened to take.
110+
// `--app` rides every leg: the reader is a projection and the daemon's scope table is the one
111+
// decision, so a named app reaches that table whichever branch the grammar took.
142112
const base = { ...selectionOptionsFromFlags(flags), app: flags.targetApp };
143113
const setting = positionals[0];
144114
const state = positionals[1];
@@ -181,8 +151,20 @@ function readSettingsOptionsFromPositionals(
181151
};
182152
}
183153
if (setting === 'clear-app-state') {
184-
// The positional this setting has always taken wins over the flag both spellings share.
154+
// The positional this setting has always taken, but a second app named on the flag is a
155+
// contradiction rather than a default: refusing it is the same rule as every other leg, that a
156+
// named app is never silently dropped.
185157
const positionalApp = state === 'clear' ? positionals[2] : state;
158+
if (
159+
positionalApp !== undefined &&
160+
flags.targetApp !== undefined &&
161+
positionalApp !== flags.targetApp
162+
) {
163+
throw new AppError(
164+
'INVALID_ARGS',
165+
`settings clear-app-state names two apps: ${positionalApp} and ${flags.targetApp}. Name one.`,
166+
);
167+
}
186168
return { ...base, setting, state: 'clear', app: positionalApp ?? flags.targetApp };
187169
}
188170
if (setting === 'reset-keychain' && state === 'clear' && positionals.length === 2) {

0 commit comments

Comments
 (0)