Skip to content

Commit 8eaefa3

Browse files
committed
feat(settings): let permission and iOS location target an explicit app
`settings permission` and the iOS-simulator `settings location on|off` privacy change acted only on the app the session had open, so setting a permission before an app's first launch meant opening the app first just to bind it. `simctl privacy` and Android's `pm` need only the bundle id or package, so the requirement was the daemon never being handed one. The named app now rides the request's input payload the way a gesture payload does: `app` is no CLI flag key, and permission's positionals already carry the target and mode. The CLI reaches it through the `--app` option `doctor` already owns, and the client and MCP surfaces through their `app` field, which is now documented. `clear-app-state` keeps carrying its app positionally, unchanged. Where a mutation cannot consume an app at all the request is refused rather than silently dropped: Android's `location on|off` writes the device's `location_mode`, and a macOS permission is a TCC grant to the host process. `settingsAppScope` is that one table, and the refusal carries `setting_app_not_consumed` with `dispatched: no` so a driver branches on the reason and knows no device was touched. No permission is set on a device that never held the app installed differently: the owner resolves the id as it always has, and the Android rule that revoking a granted permission kills the app (#1796) is unchanged.
1 parent 2212eac commit 8eaefa3

13 files changed

Lines changed: 707 additions & 19 deletions

File tree

‎packages/command-registry/src/command-schema.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,15 @@ export type CommandSchema = {
2222
*/
2323
flagsByAction?: Readonly<Record<string, readonly FlagKey[]>>;
2424
supportedFlags?: readonly FlagKey[];
25+
/**
26+
* Options this command consumes only when the caller typed them. Config, env, and remote-config
27+
* defaults still fill the flag bag — every other reader of the key keeps its default — but the
28+
* parser strips a value the command line never named before the input reader sees it, so an
29+
* operator-wide default can never stand in for a per-invocation argument. Use it where the key
30+
* selects the subject a mutation acts on (`settings --app`), because silently mutating a default
31+
* target is worse than ignoring an option the caller never asked for.
32+
*/
33+
explicitOnlyFlags?: readonly FlagKey[];
2534
/**
2635
* Replaces the generated synopsis grammar in `--help`, for shapes the generator cannot express.
2736
* The flag tail after it stays generated from `usageFlags`, so this string never restates the

‎packages/command-registry/src/flag-definitions-target.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,8 @@ export const TARGET_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
8585
names: ['--app', '--target-app'],
8686
type: 'string',
8787
usageLabel: '--app <id-or-name>',
88-
usageDescription: 'Doctor: verify an installed target app without opening a session',
88+
usageDescription:
89+
'Target an app without opening it: doctor verifies an installed app by id or name; settings applies an app-scoped change (permission, iOS location) to a bundle id or package',
8990
projectConfig: false,
9091
recorded: false,
9192
},

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

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,20 @@ export type SettingsUpdateOptions =
2929
state: 'clear';
3030
})
3131
| (DeviceCommandBaseOptions & {
32-
setting: 'wifi' | 'airplane' | 'location';
32+
setting: 'wifi' | 'airplane';
3333
state: 'on' | 'off';
3434
})
35+
/**
36+
* On Apple simulators `on`/`off` grants or revokes the app's location permission, so this leg
37+
* takes the same explicit `app` as `permission` and defaults to the session app. On Android the
38+
* toggle writes the global `location_mode` and consumes no app, so naming one there is refused
39+
* rather than dropped; `settingsAppScope` is the declaration.
40+
*/
41+
| (DeviceCommandBaseOptions & {
42+
setting: 'location';
43+
state: 'on' | 'off';
44+
app?: string;
45+
})
3546
| (DeviceCommandBaseOptions & {
3647
setting: 'location';
3748
state: 'set';
@@ -68,4 +79,11 @@ export type SettingsUpdateOptions =
6879
state: PermissionAction;
6980
permission: PermissionTarget;
7081
mode?: PermissionMode;
82+
/**
83+
* The app the permission changes, by bundle id or package name. Without it the app bound to
84+
* 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 TCC grants, so naming an
86+
* app there is refused rather than dropped.
87+
*/
88+
app?: string;
7189
});

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

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,9 @@ import {
1717
PERMISSION_ACTIONS,
1818
PERMISSION_MODES,
1919
readTextSizeCategory,
20+
settingsAppNotConsumedRefusal,
21+
settingsAppScope,
22+
SETTINGS_APP_NOT_CONSUMED_REASON,
2023
SETTINGS_INVALID_ARGS_MESSAGE,
2124
SETTINGS_MACOS_PERMISSION_USAGE,
2225
SETTINGS_USAGE_OVERRIDE,
@@ -331,3 +334,79 @@ describe('appearance vocabulary types', () => {
331334
>();
332335
});
333336
});
337+
338+
describe('settingsAppScope', () => {
339+
test('a permission is app-scoped on every mobile target and host-level on macOS', () => {
340+
expect(settingsAppScope('apple', 'permission', 'grant')).toBe('app-scoped');
341+
expect(settingsAppScope('mobile', 'permission', 'deny')).toBe('app-scoped');
342+
expect(settingsAppScope('macos-host', 'permission', 'grant')).toBe('device-level');
343+
});
344+
345+
test('clear-app-state is app-scoped wherever it is served', () => {
346+
expect(settingsAppScope('apple', 'clear-app-state', 'clear')).toBe('app-scoped');
347+
expect(settingsAppScope('mobile', 'clear-app-state', 'clear')).toBe('app-scoped');
348+
expect(settingsAppScope('macos-host', 'clear-app-state', 'clear')).toBe('unknown');
349+
});
350+
351+
test('an on/off location is app-scoped only where it maps to a privacy grant', () => {
352+
expect(settingsAppScope('apple', 'location', 'on')).toBe('app-scoped');
353+
expect(settingsAppScope('apple', 'location', 'off')).toBe('app-scoped');
354+
expect(settingsAppScope('mobile', 'location', 'on')).toBe('device-level');
355+
expect(settingsAppScope('mobile', 'location', 'off')).toBe('device-level');
356+
});
357+
358+
test('every state parseSettingState accepts classifies like its on/off spelling', () => {
359+
// The owners toggle on `parseSettingState`, which also accepts true/1/false/0. A spelling the
360+
// parser takes must settle the app scope the same way, or `location 1 --app X` silently drops X.
361+
for (const state of ['on', 'true', 'TRUE', '1']) {
362+
expect(parseSettingState(state)).toBe(true);
363+
expect(settingsAppScope('apple', 'location', state)).toBe('app-scoped');
364+
expect(settingsAppScope('mobile', 'location', state)).toBe('device-level');
365+
}
366+
for (const state of ['off', 'false', 'FALSE', '0']) {
367+
expect(parseSettingState(state)).toBe(false);
368+
expect(settingsAppScope('apple', 'location', state)).toBe('app-scoped');
369+
expect(settingsAppScope('mobile', 'location', state)).toBe('device-level');
370+
}
371+
// The table trims before consulting the grammar, so a padded spelling still classifies.
372+
expect(settingsAppScope('apple', 'location', ' on ')).toBe('app-scoped');
373+
});
374+
375+
test('a location set moves the device itself for everyone', () => {
376+
expect(settingsAppScope('apple', 'location', 'set')).toBe('device-level');
377+
expect(settingsAppScope('mobile', 'location', 'set')).toBe('device-level');
378+
});
379+
380+
test('a combination the table does not settle stays unknown, not a verdict', () => {
381+
expect(settingsAppScope('macos-host', 'location', 'on')).toBe('unknown');
382+
expect(settingsAppScope('mobile', 'wifi', 'on')).toBe('unknown');
383+
expect(settingsAppScope('apple', 'animations', 'on')).toBe('unknown');
384+
expect(settingsAppScope('mobile', 'location', 'sideways')).toBe('unknown');
385+
// A mutation with no state is not a write the surface admits, so the table names no scope for it.
386+
expect(settingsAppScope('apple', 'location', undefined)).toBe('unknown');
387+
});
388+
389+
test('the scope keys on the setting and state vocabulary, not its padding or case', () => {
390+
expect(settingsAppScope('apple', ' PERMISSION ', 'GRANT')).toBe('app-scoped');
391+
expect(settingsAppScope('mobile', 'Location', ' On ')).toBe('device-level');
392+
});
393+
});
394+
395+
describe('settingsAppNotConsumedRefusal', () => {
396+
test('refuses by naming the mutation and quoting the app back', () => {
397+
const refusal = settingsAppNotConsumedRefusal('location', 'on', 'com.example.app');
398+
expect(refusal.code).toBe('INVALID_ARGS');
399+
expect(refusal.message).toContain('settings location on');
400+
expect(refusal.message).toContain('com.example.app');
401+
expect(refusal.details.reason).toBe(SETTINGS_APP_NOT_CONSUMED_REASON);
402+
expect(refusal.details.dispatched).toBe('no');
403+
expect(refusal.details.app).toBe('com.example.app');
404+
expect(refusal.hint).toContain('settings permission grant location --app com.example.app');
405+
});
406+
407+
test('a stateless mutation is named by its setting alone', () => {
408+
expect(
409+
settingsAppNotConsumedRefusal('permission', undefined, 'com.example.app').message,
410+
).toContain('settings permission applies to the target itself');
411+
});
412+
});

‎packages/contracts/src/settings.ts‎

Lines changed: 120 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -151,6 +151,112 @@ export type SettingOptions = {
151151
longitude?: number;
152152
};
153153

154+
/**
155+
* Whether naming an app for one mutation can mean anything on one target.
156+
*
157+
* `app-scoped` is the shape the public `app` field exists for: the change lands on that bundle id
158+
* or package (`simctl privacy`, Android's `pm`). `device-level` is a mutation the same command
159+
* serves for the whole device: Android's on/off `location` writes the global `location_mode`, and
160+
* the macOS host's permissions are TCC grants to the host process, so neither can consume an app.
161+
* `unknown` covers every combination this table does not settle — a setting with no app shape and no
162+
* device-wide write of its own (`wifi` on the macOS host) among them — and is deliberately not a
163+
* verdict: support belongs to the owner's runtime fact, which answers a setting it does not serve
164+
* (`permission` on HarmonyOS) with its own refusal rather than with a complaint about an argument it
165+
* never read.
166+
*/
167+
export type SettingsAppScope = 'app-scoped' | 'device-level' | 'unknown';
168+
169+
/**
170+
* What kind of target a `settings` mutation runs on, as far as consuming an app is concerned:
171+
* the Apple family, the macOS host, or the non-Apple targets that share the mobile app shape
172+
* (Android, HarmonyOS, Vega, Linux, web). The daemon derives it from a device with the kernel's
173+
* own predicates; being app-scoped here is a claim about the shape of the change, never about
174+
* support — an owner that serves no such setting answers with its own refusal.
175+
*/
176+
export type SettingsTargetFamily = 'apple' | 'mobile' | 'macos-host';
177+
178+
/**
179+
* The one table deciding whether an app named on a `settings` request is consumed. It is keyed on
180+
* the target family, a fact the daemon derives from the device before binding a runtime, and it
181+
* stays honest by settling only the combinations whose owner behavior is already fixed elsewhere:
182+
* `clear-app-state` is app-scoped wherever it is served (`isMacOsSettingSupported` keeps macOS out
183+
* of that claim), `permission` is app-scoped on every non-Apple mobile target and on Apple and
184+
* host-level on macOS, and on/off `location` is app-scoped only on Apple, where it maps to a
185+
* privacy grant — while `location set` moves the device's own location for everyone.
186+
*/
187+
export function settingsAppScope(
188+
family: SettingsTargetFamily,
189+
setting: string,
190+
state: string | undefined,
191+
): SettingsAppScope {
192+
const normalizedSetting = setting.trim().toLowerCase();
193+
if (normalizedSetting === 'clear-app-state') {
194+
return family === 'macos-host' ? 'unknown' : 'app-scoped';
195+
}
196+
if (normalizedSetting === 'permission') {
197+
return family === 'macos-host' ? 'device-level' : 'app-scoped';
198+
}
199+
if (normalizedSetting === 'location') return locationAppScope(family, state);
200+
return 'unknown';
201+
}
202+
203+
/**
204+
* One on/off `location` is a privacy grant only on Apple, where it maps to `simctl privacy`; on
205+
* the other mobile targets it writes the global `location_mode`, and `set` moves the device's own
206+
* location for everyone. A state this ladder does not name settles nothing, and the macOS host,
207+
* whose location surface `isMacOsSettingSupported` keeps out of the settings vocabulary, is no
208+
* verdict either.
209+
*/
210+
function locationAppScope(
211+
family: SettingsTargetFamily,
212+
state: string | undefined,
213+
): SettingsAppScope {
214+
const normalizedState = state?.trim().toLowerCase();
215+
if (normalizedState === 'set') return 'device-level';
216+
if (readSettingState(normalizedState) === undefined) return 'unknown';
217+
if (family === 'apple') return 'app-scoped';
218+
if (family === 'mobile') return 'device-level';
219+
return 'unknown';
220+
}
221+
222+
/**
223+
* The reason a request is told its app names nothing: what a caller does about it — drop the app or
224+
* move to a target whose mutation is app-scoped — is the reason's meaning, so a driver can branch
225+
* on `error.details.reason` instead of the prose. Paired with `dispatched: no`, because the
226+
* refusal runs before a device is touched.
227+
*/
228+
export const SETTINGS_APP_NOT_CONSUMED_REASON = 'setting_app_not_consumed';
229+
230+
/**
231+
* The refusal a mutation answers with when its target consumes no app: the code, sentence, typed
232+
* details, and hint as data, so the daemon can answer with it through its own response builder
233+
* rather than by unwrapping an error the CLI would then re-normalize. The `app` that named nothing
234+
* stays in `details` — the caller asked about that bundle id and the answer should quote it back.
235+
*/
236+
export function settingsAppNotConsumedRefusal(
237+
setting: string,
238+
state: string | undefined,
239+
app: string,
240+
): {
241+
code: 'INVALID_ARGS';
242+
message: string;
243+
details: Record<string, unknown>;
244+
hint: string;
245+
} {
246+
const described = state === undefined ? setting : `${setting} ${state}`;
247+
return {
248+
code: 'INVALID_ARGS',
249+
message: `settings ${described} applies to the target itself, not to an app: ${app} names nothing it can grant or revoke.`,
250+
details: {
251+
reason: SETTINGS_APP_NOT_CONSUMED_REASON,
252+
dispatched: 'no',
253+
setting: described,
254+
app,
255+
},
256+
hint: `Drop the --app option and run \`settings ${described}\`, or aim the app at an app-scoped setting such as \`settings permission grant location --app ${app}\`.`,
257+
};
258+
}
259+
154260
const SETTINGS_WIFI_USAGE = '<wifi|airplane|location> <on|off>';
155261
const SETTINGS_LOCATION_SET_USAGE = 'location set <lat> <lon>';
156262
const SETTINGS_ANIMATIONS_USAGE = 'animations <on|off>';
@@ -299,10 +405,22 @@ export function parseAppearanceAction(state: string): AppearanceAction {
299405
);
300406
}
301407

302-
/** The boolean a `settings <setting> <state>` positional spells, in any casing. */
303-
export function parseSettingState(state: string): boolean {
408+
/**
409+
* The boolean a `settings <setting> <state>` positional spells, or `undefined` when it spells none.
410+
* This is the grammar `parseSettingState` refuses on and the app-scope table classifies with, so a
411+
* state the owners accept can never settle differently about an app than it settles about the toggle.
412+
*/
413+
function readSettingState(state: string | undefined): boolean | undefined {
414+
if (state === undefined) return undefined;
304415
const normalized = state.toLowerCase();
305416
if (SETTING_STATE_ON.includes(normalized)) return true;
306417
if (SETTING_STATE_OFF.includes(normalized)) return false;
418+
return undefined;
419+
}
420+
421+
/** The boolean a `settings <setting> <state>` positional spells, in any casing. */
422+
export function parseSettingState(state: string): boolean {
423+
const parsed = readSettingState(state);
424+
if (parsed !== undefined) return parsed;
307425
throw new AppError('INVALID_ARGS', `Invalid setting state: ${state}`);
308426
}

‎src/cli/parser/args.ts‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -215,6 +215,7 @@ export function finalizeParsedArgs(
215215
delete (flags as Record<string, unknown>)[key];
216216
}
217217
}
218+
stripFlagsTheCommandTreatsAsExplicitOnly(parsed, flags);
218219
assertNoConflictingBackModeFlags(parsed);
219220
applyCommandDefaults(parsed.command, flags);
220221
const normalized = normalizeParsedCommandAliases({
@@ -385,6 +386,22 @@ function normalizeParsedCommandAliases(parsed: ParsedArgs): ParsedArgs {
385386
return parsed;
386387
}
387388

389+
/**
390+
* Drops a declared explicit-only option whose value arrived only from config, env, or remote-config
391+
* defaults. `providedFlags` records what the command line typed, so a key absent from it is a default
392+
* the command must not consume: `settings permission grant camera` mutates the session app even when
393+
* AGENT_DEVICE_TARGET_APP names a different one. A typed value stays untouched.
394+
*/
395+
function stripFlagsTheCommandTreatsAsExplicitOnly(parsed: RawParsedArgs, flags: CliFlags): void {
396+
const explicitOnly = getCommandSchema(parsed.command)?.explicitOnlyFlags;
397+
if (explicitOnly === undefined) return;
398+
const typedKeys = new Set(parsed.providedFlags.map((entry) => entry.key));
399+
for (const key of explicitOnly) {
400+
if (typedKeys.has(key)) continue;
401+
delete (flags as Record<string, unknown>)[key];
402+
}
403+
}
404+
388405
/**
389406
* The typed options the selected action of a command cannot read.
390407
*

‎src/cli/resolve-cli-options.test.ts‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,3 +38,40 @@ test('a frame rate the caller typed stays a typed flag', () => {
3838
['fps'],
3939
);
4040
});
41+
42+
// #3179: settings consumes --app only when this invocation typed it. A mutation that silently
43+
// landed on AGENT_DEVICE_TARGET_APP would change permissions for an app the caller never named,
44+
// while `doctor --app` (and its env default) still reads a configured default app by design.
45+
test('an app from the environment never reaches a settings mutation', () => {
46+
const parsed = resolveCliOptions(['settings', 'permission', 'grant', 'camera'], {
47+
cwd: process.cwd(),
48+
env: isolatedEnv({ AGENT_DEVICE_TARGET_APP: 'com.example.configured' }),
49+
});
50+
51+
assert.equal(parsed.flags.targetApp, undefined);
52+
assert.deepEqual(
53+
parsed.providedFlags.map((entry) => entry.key),
54+
[],
55+
);
56+
});
57+
58+
test('a typed --app still reaches a settings mutation', () => {
59+
const parsed = resolveCliOptions(
60+
['settings', 'permission', 'grant', 'camera', '--app', 'com.example.typed'],
61+
{
62+
cwd: process.cwd(),
63+
env: isolatedEnv({ AGENT_DEVICE_TARGET_APP: 'com.example.configured' }),
64+
},
65+
);
66+
67+
assert.equal(parsed.flags.targetApp, 'com.example.typed');
68+
});
69+
70+
test('the same env default keeps filling doctor, which reads a configured app without a mutation', () => {
71+
const parsed = resolveCliOptions(['doctor'], {
72+
cwd: process.cwd(),
73+
env: isolatedEnv({ AGENT_DEVICE_TARGET_APP: 'com.example.configured' }),
74+
});
75+
76+
assert.equal(parsed.flags.targetApp, 'com.example.configured');
77+
});

0 commit comments

Comments
 (0)