Skip to content

Commit da76aa4

Browse files
authored
refactor(commands): declare project-config admission and recorder sanitization on the flag declaration (#2453)
* refactor(commands): declare project-config admission and recorder sanitization on the flag declaration Move the two fail-closed flag properties — may a key be set from a project `agent-device.json`, and does the session recorder copy it into `SessionAction.flags` — off the hand-maintained allowlists and onto each `FlagDefinition` as required `projectConfig` / `recorded` fields. Omitting either is now a type error, so the compiler holds the fail-closed property a list held by omission. - 156 declarations carry both fields; the 6 screenshot-specific definitions carry them too. Populated to match the old sets exactly (one-off diff empty: 85 project-config and 39 recorded keys, byte-for-byte). - `cli-config.ts` and `session-action-recorder.ts` derive their sets from the registry and no longer list keys; `RECORDED`/`PROJECT_CONFIG` derivations recomputed per call so a consumer builds its set at its own module load. Recorder reaches the derivation through the `cli-schema/command-schema.ts` seam (daemon may not import `commands/`). - Planted-divergence tests, per #2421: flipping one declaration's field moves the admission/sanitization outcome through the production derivation, plus a compile-time pin that an incomplete declaration does not build. - `docs/agents/cli-flags.md` now points at the declaration fields, not the allowlist. Refs #2445 * refactor(commands): return the recorded keys as a set, matching project-config Both derivations answer the same question — the set of flag keys a surface admits — so both return ReadonlySet<FlagKey>. Drops a needless set-then-spread on the recorder path; consumers already iterate the value. Refs #2445 * fix(commands): keep the CommandFlags guard on recorded flag declarations The deleted `SANITIZED_FLAG_KEYS` was `satisfies readonly (keyof CommandFlags)[]`, so every recorded key had to be a `CommandFlags` key. The derived set returns `FlagKey` and the recorder indexed it through a cast, so `recorded: true` on a CLI-only key (`daemonAuthToken`, `help`, …) compiled and could leak an uncarrable value into a recorded action. State the constraint on the declaration: `FlagDefinition` is a union that locks `recorded` to `false` for a `NonRecordableFlagKey = Exclude<FlagKey, keyof CommandFlags>`. `recordedFlagKeys()` returns `ReadonlySet<RecordableFlagKey>` via a narrowing predicate, so `sanitizeFlags` drops its cast. Adds a `@ts-expect-error` test that a CLI-only key cannot opt into recording. Refs #2445
1 parent 2d109e5 commit da76aa4

12 files changed

Lines changed: 589 additions & 149 deletions

‎docs/agents/cli-flags.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,12 @@ Thread a flag only through the layers that consume it:
88
flag; find the owner with
99
`rg -n "<command>|supportedFlags|allowedFlags" src/commands src/cli-schema src/cli/parser`. For
1010
schema-only CLI commands, the owner is `SCHEMA_ONLY_CLI_COMMAND_SCHEMAS` in
11-
`src/cli-schema/command-overrides.ts`. New flags are operator-only by default. Add a flag to `PROJECT_CONFIG_FLAG_KEYS` in
12-
`src/cli-schema/cli-config.ts` only when repository control is safe; this positive allowlist is
13-
the completeness gate.
11+
`src/cli-schema/command-overrides.ts`. Every flag declaration states `projectConfig`
12+
(may be set from a project `agent-device.json`) and `recorded` (the session recorder
13+
copies it into `SessionAction.flags`). Both are required, so a new declaration that
14+
omits either does not compile — that, not an allowlist, is the completeness gate. Set
15+
`projectConfig: true` only when repository control is safe; a new flag is otherwise
16+
operator-only. Set `recorded: true` only when a `.ad` recording must carry the flag.
1417
2. `src/commands/cli-grammar/*`: read the CLI flag into command input.
1518
3. `src/commands/command-projection.ts` and command-family projection helpers: write the input into
1619
the daemon request only if the flag affects daemon execution.

‎packages/contracts/src/screenshot.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,8 @@ type ScreenshotSpecificFlagDefinition = {
9797
max?: number;
9898
usageLabel: string;
9999
usageDescription: string;
100+
projectConfig: boolean;
101+
recorded: boolean;
100102
};
101103

102104
export const SCREENSHOT_SPECIFIC_FLAG_DEFINITIONS: readonly ScreenshotSpecificFlagDefinition[] = [
@@ -107,6 +109,8 @@ export const SCREENSHOT_SPECIFIC_FLAG_DEFINITIONS: readonly ScreenshotSpecificFl
107109
usageLabel: '--crop-on <selector-expression>',
108110
usageDescription:
109111
'Screenshot: crop the capture to the frame of the selector resolved on the same screen',
112+
projectConfig: false,
113+
recorded: true,
110114
},
111115
{
112116
key: 'screenshotPixelDensity',
@@ -116,6 +120,8 @@ export const SCREENSHOT_SPECIFIC_FLAG_DEFINITIONS: readonly ScreenshotSpecificFl
116120
usageLabel: '--pixel-density <n>',
117121
usageDescription:
118122
'Screenshot: output PNG pixel density in pixels per logical point (currently supported on iOS simulators)',
123+
projectConfig: true,
124+
recorded: true,
119125
},
120126
{
121127
key: 'screenshotFullscreen',
@@ -124,6 +130,8 @@ export const SCREENSHOT_SPECIFIC_FLAG_DEFINITIONS: readonly ScreenshotSpecificFl
124130
usageLabel: '--fullscreen, --full, -f',
125131
usageDescription:
126132
'Screenshot: on web capture the full page; on macOS app sessions capture the full desktop instead of the app window',
133+
projectConfig: true,
134+
recorded: true,
127135
},
128136
{
129137
key: 'screenshotScale',
@@ -134,6 +142,8 @@ export const SCREENSHOT_SPECIFIC_FLAG_DEFINITIONS: readonly ScreenshotSpecificFl
134142
usageLabel: '--scale <0.01-1>',
135143
usageDescription:
136144
'Screenshot: resize both dimensions by this factor (or use AGENT_DEVICE_SCREENSHOT_SCALE)',
145+
projectConfig: true,
146+
recorded: true,
137147
},
138148
{
139149
key: 'screenshotNoStabilize',
@@ -142,6 +152,8 @@ export const SCREENSHOT_SPECIFIC_FLAG_DEFINITIONS: readonly ScreenshotSpecificFl
142152
usageLabel: '--no-stabilize',
143153
usageDescription:
144154
'Screenshot: skip Android demo-mode/status-bar stabilization and settle delay for low-latency capture loops',
155+
projectConfig: true,
156+
recorded: true,
145157
},
146158
{
147159
key: 'screenshotNormalizeStatusBar',
@@ -150,6 +162,8 @@ export const SCREENSHOT_SPECIFIC_FLAG_DEFINITIONS: readonly ScreenshotSpecificFl
150162
usageLabel: '--normalize-status-bar',
151163
usageDescription:
152164
'Screenshot: on iOS simulators temporarily normalize status-bar chrome for deterministic screenshot diffs',
165+
projectConfig: true,
166+
recorded: true,
153167
},
154168
];
155169

‎src/cli-schema/cli-config.ts‎

Lines changed: 5 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import path from 'node:path';
44
import { AppError } from '@agent-device/kernel/errors';
55
import { mergeDefinedFlags } from './merge-flags.ts';
66
import { type FlagKey } from '../commands/cli-grammar/flag-types.ts';
7+
import { projectConfigFlagKeys } from './command-schema.ts';
78
import { expandUserHomePath, resolveUserPath } from '@agent-device/host-kit/file';
89
import {
910
getConfigurableOptionSpecs,
@@ -32,95 +33,10 @@ type ConfigFileSource = 'user' | 'project' | 'explicit';
3233

3334
type ConfigPath = { path: string; required: boolean; source: ConfigFileSource };
3435

35-
// Project config is repository-controlled, so new flags are operator-only by default.
36-
// Adding a key here is the only way to make it available to ./agent-device.json.
37-
const PROJECT_CONFIG_FLAG_KEYS = new Set<FlagKey>([
38-
'json',
39-
'platform',
40-
'target',
41-
'device',
42-
'udid',
43-
'serial',
44-
'session',
45-
'sessionLock',
46-
'activity',
47-
'launchArgs',
48-
'launchUrl',
49-
'remote',
50-
'deviceHub',
51-
'testIme',
52-
'appsFilter',
53-
'clean',
54-
'force',
55-
'stale',
56-
'relaunch',
57-
'shutdown',
58-
'surface',
59-
'headless',
60-
'restart',
61-
'noRecord',
62-
'record',
63-
'recordAs',
64-
'snapshotInteractiveOnly',
65-
'snapshotDiff',
66-
'snapshotDepth',
67-
'snapshotScope',
68-
'snapshotRaw',
69-
'snapshotCustomActions',
70-
'snapshotForceFull',
71-
'screenshotPixelDensity',
72-
'screenshotFullscreen',
73-
'screenshotScale',
74-
'screenshotNoStabilize',
75-
'screenshotNormalizeStatusBar',
76-
'overlayRefs',
77-
'networkInclude',
78-
'baseline',
79-
'threshold',
80-
'count',
81-
'pointerCount',
82-
'fps',
83-
'quality',
84-
'hideTouches',
85-
'recordingScope',
86-
'intervalMs',
87-
'delayMs',
88-
'durationMs',
89-
'holdMs',
90-
'jitterPx',
91-
'pixels',
92-
'doubleTap',
93-
'verify',
94-
'settle',
95-
'settleQuietMs',
96-
'clickButton',
97-
'backMode',
98-
'pauseMs',
99-
'pattern',
100-
'kind',
101-
'perfTemplate',
102-
'responseLevel',
103-
'verbose',
104-
'cost',
105-
'timeoutMs',
106-
'retries',
107-
'failFast',
108-
'recordVideo',
109-
'replayUpdate',
110-
'replayMaestro',
111-
'replayFrom',
112-
'replayPlanDigest',
113-
'replayKeepSession',
114-
'findFirst',
115-
'findLast',
116-
'batchOnError',
117-
'batchMaxSteps',
118-
'retainPaths',
119-
'retentionMs',
120-
'shardAll',
121-
'shardSplit',
122-
'noLogin',
123-
]);
36+
// Project config is repository-controlled, so a flag stays operator-only unless its
37+
// own declaration sets `projectConfig: true`. This set derives from those declarations;
38+
// admitting a new key to ./agent-device.json edits the declaration, not this file.
39+
const PROJECT_CONFIG_FLAG_KEYS = projectConfigFlagKeys();
12440

12541
function resolveConfigPaths(
12642
cwd: string,

‎src/cli-schema/command-schema.ts‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,12 @@ import type { CliCommandName } from '@agent-device/command-registry/catalog';
22
import { listCommandMetadata } from '../commands/command-metadata.ts';
33
import type { CommandSchema } from './types.ts';
44
import { getCliCommandOverride, getSchemaOnlyCliCommandSchema } from './command-overrides.ts';
5-
import { getFlagDefinition, getFlagDefinitions } from '../commands/cli-grammar/flag-registry.ts';
5+
import {
6+
getFlagDefinition,
7+
getFlagDefinitions,
8+
projectConfigFlagKeys,
9+
recordedFlagKeys,
10+
} from '../commands/cli-grammar/flag-registry.ts';
611
import {
712
COMMON_COMMAND_SUPPORTED_FLAG_KEYS,
813
DEVICE_SELECTION_FLAG_KEYS,
@@ -13,7 +18,14 @@ import { AppError } from '@agent-device/kernel/errors';
1318

1419
export type { FlagDefinition, FlagKey };
1520
export type { CommandSchema };
16-
export { DEVICE_SELECTION_FLAG_KEYS, getFlagDefinition, getFlagDefinitions, GLOBAL_FLAG_KEYS };
21+
export {
22+
DEVICE_SELECTION_FLAG_KEYS,
23+
getFlagDefinition,
24+
getFlagDefinitions,
25+
GLOBAL_FLAG_KEYS,
26+
projectConfigFlagKeys,
27+
recordedFlagKeys,
28+
};
1729

1830
// Bases hold only the flags every command supports; prose arrives with the facet's schema,
1931
// which always carries a complete `text`.
Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
import assert from 'node:assert/strict';
2+
import fs from 'node:fs';
3+
import path from 'node:path';
4+
import { test, vi } from 'vitest';
5+
import type { CliFlags } from '@agent-device/contracts/command';
6+
import { getFlagDefinitionsForKey } from './flag-registry.ts';
7+
import type { FlagDefinition } from './flag-types.ts';
8+
import { resolveConfigBackedFlagDefaults } from '../../cli-schema/cli-config.ts';
9+
import { recordActionEntry } from '../../daemon/session-action-recorder.ts';
10+
import { makeIosSession } from '../../__tests__/test-utils/session-factories.ts';
11+
import { makeTempWorkspace } from '../../__tests__/cli-config-fixtures.ts';
12+
13+
/**
14+
* These are planted-divergence tests, not membership snapshots. A snapshot would
15+
* re-list the admitted/recorded keys and drift exactly like the two hand-maintained
16+
* allowlists it replaced; these plant a divergence in the ONE declaration and require
17+
* the production derivation to follow it, which a second list could not do.
18+
*
19+
* Like #2421's `command-input-option-field.test.ts`, the plant lands BEFORE the surface
20+
* is built. `cli-config.ts` freezes `PROJECT_CONFIG_FLAG_KEYS` and the recorder freezes
21+
* `RECORDED_FLAG_KEYS` at their own module load, so each test resets the graph, writes
22+
* the divergence onto the live declaration, and only then imports the consumer — so what
23+
* it observes is the real derivation running over the planted declaration.
24+
*/
25+
26+
const OPERATOR_CLI_FLAGS: CliFlags = { json: false, help: false, version: false };
27+
28+
function writeProjectConfig(project: string, entries: Record<string, unknown>): void {
29+
fs.writeFileSync(path.join(project, 'agent-device.json'), JSON.stringify(entries), 'utf8');
30+
}
31+
32+
function declarationFor(key: 'daemonBaseUrl' | 'overlayRefs'): FlagDefinition {
33+
const declaration = getFlagDefinitionsForKey(key)[0];
34+
assert.ok(declaration, `expected a declaration for ${key}`);
35+
return declaration;
36+
}
37+
38+
test('project-config admission follows the declaration: an undeclared key is refused, a planted declaration is admitted', async () => {
39+
// Shipped: the declaration declines project config, so the same file the shipped
40+
// derivation reads is rejected.
41+
assert.equal(declarationFor('daemonBaseUrl').projectConfig, false);
42+
const shipped = makeTempWorkspace();
43+
try {
44+
writeProjectConfig(shipped.project, { daemonBaseUrl: 'https://daemon.example.test' });
45+
assert.throws(
46+
() =>
47+
resolveConfigBackedFlagDefaults({
48+
command: 'devices',
49+
cwd: shipped.project,
50+
cliFlags: OPERATOR_CLI_FLAGS,
51+
env: { HOME: shipped.home },
52+
}),
53+
/not allowed in project config file/,
54+
);
55+
} finally {
56+
fs.rmSync(shipped.root, { recursive: true, force: true });
57+
}
58+
59+
// Planted: flip the declaration before `cli-config` builds, and the identical file is
60+
// admitted. A hand-maintained allowlist in `cli-config.ts` could not follow this.
61+
vi.resetModules();
62+
const registry = await import('./flag-registry.ts');
63+
const planted = getInRegistry(registry, 'daemonBaseUrl');
64+
Object.assign(planted, { projectConfig: true });
65+
const { resolveConfigBackedFlagDefaults: derivePlanted } =
66+
await import('../../cli-schema/cli-config.ts');
67+
const workspace = makeTempWorkspace();
68+
try {
69+
writeProjectConfig(workspace.project, { daemonBaseUrl: 'https://daemon.example.test' });
70+
const defaults = derivePlanted({
71+
command: 'devices',
72+
cwd: workspace.project,
73+
cliFlags: OPERATOR_CLI_FLAGS,
74+
env: { HOME: workspace.home },
75+
});
76+
assert.equal(defaults.daemonBaseUrl, 'https://daemon.example.test');
77+
} finally {
78+
fs.rmSync(workspace.root, { recursive: true, force: true });
79+
}
80+
});
81+
82+
test('recorder sanitization follows the declaration: an undeclared key is dropped, a planted declaration is recorded', async () => {
83+
// Shipped: `overlayRefs` declines recording so it is dropped; `fps` (recorded) is the
84+
// control that proves the copy itself works.
85+
assert.equal(declarationFor('overlayRefs').recorded, false);
86+
const shipped = recordActionEntry(makeIosSession('default'), {
87+
command: 'screenshot',
88+
positionals: [],
89+
flags: { overlayRefs: true, fps: 5 },
90+
result: {},
91+
});
92+
assert.equal(shipped?.flags.overlayRefs, undefined, 'overlayRefs is undeclared for recording');
93+
assert.equal(shipped?.flags.fps, 5, 'fps is declared for recording');
94+
95+
// Planted: flip the declaration before the recorder builds, and the production
96+
// `sanitizeFlags` now copies the same value.
97+
vi.resetModules();
98+
const registry = await import('./flag-registry.ts');
99+
const planted = getInRegistry(registry, 'overlayRefs');
100+
Object.assign(planted, { recorded: true });
101+
const { recordActionEntry: recordPlanted } =
102+
await import('../../daemon/session-action-recorder.ts');
103+
const recorded = recordPlanted(makeIosSession('default'), {
104+
command: 'screenshot',
105+
positionals: [],
106+
flags: { overlayRefs: true },
107+
result: {},
108+
});
109+
assert.equal(recorded?.flags.overlayRefs, true, 'a planted declaration is copied');
110+
});
111+
112+
test('a flag declaration without both admission fields does not compile', () => {
113+
// @ts-expect-error projectConfig and recorded are required; omission is the fail-closed gate.
114+
const declaration: FlagDefinition = { key: 'json', names: ['--json'], type: 'boolean' };
115+
assert.ok(declaration);
116+
});
117+
118+
test('a CLI-only key cannot opt into recording', () => {
119+
// `help` is a CLI token that never reaches `CommandFlags`, so `recorded: true`
120+
// is a type error — the guard the old `satisfies keyof CommandFlags` list held.
121+
// @ts-expect-error a non-recodable key must declare `recorded: false`.
122+
const declaration: FlagDefinition = {
123+
key: 'help',
124+
names: ['--help'],
125+
type: 'boolean',
126+
projectConfig: false,
127+
recorded: true,
128+
};
129+
assert.ok(declaration);
130+
});
131+
132+
function getInRegistry(
133+
registry: typeof import('./flag-registry.ts'),
134+
key: 'daemonBaseUrl' | 'overlayRefs',
135+
): FlagDefinition {
136+
const declaration = registry.getFlagDefinitionsForKey(key)[0];
137+
assert.ok(declaration, `expected a declaration for ${key}`);
138+
return declaration;
139+
}

0 commit comments

Comments
 (0)