Skip to content

Commit baad0cc

Browse files
committed
refactor(mcp): project prepare family output schema from its owning module
Moves the single hand-authored MCP outputSchema entry for prepare out of command-output-schemas.ts into a frozen PREPARE_COMMAND_OUTPUT_SCHEMAS map exported from src/commands/management/prepare.ts, following the #2810 projection seam already used by the replay, system, interaction, device-management, push-management, viewport, recording, and capture-wait families on this stack. Registers the family in the PROJECTED_FAMILIES disjointness check and adds command-tools-management-prepare-schemas.test.ts with a reference-equality proof against the module object and an owner-file check, matching the pattern from the other projected families. prepare's descriptor declares no post-action observation trait (#1652), so no settle-graft copy applies here. The moved code is byte-identical to what command-output-schemas.ts held: same objectSchema/numberSchema/stringSchema/enumSchema/constSchema calls and field order. Verified the published outputSchema for prepare is byte-identical to origin/main by dumping COMMAND_OUTPUT_SCHEMAS.prepare as JSON on both refs. Part of #2819.
1 parent 30245eb commit baad0cc

4 files changed

Lines changed: 114 additions & 60 deletions

File tree

‎src/commands/management/prepare.ts‎

Lines changed: 79 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,97 @@
11
import { PUBLIC_COMMANDS } from '@agent-device/command-registry/catalog';
22
import type { CommandSchemaOverride } from '@agent-device/command-registry/command-schema';
3-
import { enumField, integerField, requiredField } from '../command-input.ts';
3+
import type { CommandResultMap } from '@agent-device/command-registry/command-result';
4+
import { DEVICE_KINDS, PUBLIC_PLATFORMS } from '@agent-device/kernel/device';
5+
import {
6+
constSchema,
7+
enumField,
8+
enumSchema,
9+
integerField,
10+
numberSchema,
11+
objectSchema,
12+
requiredField,
13+
stringSchema,
14+
} from '../command-input.ts';
415
import {
516
commonInputFromFlags,
617
direct,
718
requiredDaemonString,
819
requiredString,
920
} from '../cli-grammar/common.ts';
1021
import type { CliReader, DaemonWriter } from '../cli-grammar/types.ts';
22+
import type { JsonSchema } from '../command-contract.ts';
1123
import { defineCommandFacet } from '../family/types.ts';
1224
import { defineFieldCommandMetadata } from '../field-command-contract.ts';
1325
import { managementCliOutputFormatters } from './output.ts';
1426

1527
const PREPARE_ACTION_VALUES = ['ios-runner'] as const;
1628

29+
/**
30+
* This family's advertised MCP `outputSchema`, keyed by daemon command name and projected into
31+
* the command map by `src/mcp/command-output-schemas.ts`. Non-strict like every other entry: no
32+
* `additionalProperties: false`, so additive response fields keep validating. prepare is not
33+
* MCP-exposed, but the schema stays map-complete with `CommandResultMap`.
34+
*/
35+
export const PREPARE_COMMAND_OUTPUT_SCHEMAS = {
36+
// packages/contracts/src/prepare.ts
37+
prepare: objectSchema(
38+
{
39+
action: constSchema('ios-runner'),
40+
// PublicPlatform leaf, mirroring PrepareCommandResult (packages/contracts/src/prepare.ts).
41+
platform: enumSchema(PUBLIC_PLATFORMS),
42+
deviceId: stringSchema(),
43+
deviceName: stringSchema(),
44+
kind: enumSchema(DEVICE_KINDS),
45+
durationMs: numberSchema(),
46+
runner: objectSchema({}, []),
47+
cache: enumSchema(['exact', 'miss', 'external']),
48+
artifact: enumSchema(['valid', 'rebuilt']),
49+
buildMs: numberSchema(),
50+
connectMs: numberSchema(),
51+
healthCheckMs: numberSchema(),
52+
xctestrunPath: stringSchema(),
53+
recoveryReason: stringSchema(),
54+
failureReason: stringSchema(),
55+
timing: objectSchema(
56+
{
57+
totalMs: numberSchema(),
58+
additiveParts: objectSchema(
59+
{
60+
buildMs: numberSchema(),
61+
connectAfterBuildMs: numberSchema(),
62+
healthCheckMs: numberSchema(),
63+
},
64+
['connectAfterBuildMs', 'healthCheckMs'],
65+
),
66+
containment: objectSchema(
67+
{
68+
connectMs: { type: 'array', items: constSchema('buildMs') },
69+
healthCheckMs: { type: 'array', items: stringSchema() },
70+
},
71+
['healthCheckMs'],
72+
),
73+
note: stringSchema(),
74+
},
75+
['totalMs', 'additiveParts', 'containment', 'note'],
76+
),
77+
message: stringSchema(),
78+
},
79+
[
80+
'action',
81+
'platform',
82+
'deviceId',
83+
'deviceName',
84+
'kind',
85+
'durationMs',
86+
'runner',
87+
'connectMs',
88+
'healthCheckMs',
89+
'timing',
90+
'message',
91+
],
92+
),
93+
} satisfies Pick<Record<keyof CommandResultMap, JsonSchema>, 'prepare'>;
94+
1795
const prepareCommandMetadata = defineFieldCommandMetadata(
1896
'prepare',
1997
'Prepare platform helper infrastructure. ios-runner builds/reuses, starts, and health-checks the XCTest runner so later Apple snapshots and interactions do not pay first-use startup cost. In JSON output, top-level buildMs/connectMs/healthCheckMs are diagnostic fields and may overlap; use timing.additiveParts for additive wall-clock phase totals. In CI, run it after boot/install and before replay/test; if replay/test starts a separate daemon, stop the prepare daemon before replay/test so it does not keep the prepared runner lease. It is not a recovery step for "runner already owned by another agent-device daemon"; stop the owning daemon on the Mac with simulator access instead. Runner build/start output is written to the session runner.log; daemon.log is for daemon lifecycle/startup issues.',
Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
import assert from 'node:assert/strict';
2+
import { test } from 'vitest';
3+
import { ownerFilesForCommand } from '@agent-device/command-registry/owner-files';
4+
import { PREPARE_COMMAND_OUTPUT_SCHEMAS } from '../../commands/management/prepare.ts';
5+
import { COMMAND_OUTPUT_SCHEMAS } from '../command-output-schemas.ts';
6+
7+
const PREPARE_COMMANDS = Object.keys(PREPARE_COMMAND_OUTPUT_SCHEMAS) as Array<
8+
keyof typeof PREPARE_COMMAND_OUTPUT_SCHEMAS
9+
>;
10+
11+
// prepare does not carry the post-action observation trait (#1652): it is a device-runtime
12+
// command, not an interaction command, so the composed map never copies the entry and
13+
// reference equality must hold.
14+
test('MCP prepare family output schemas are the family module entries, not copies', () => {
15+
for (const command of PREPARE_COMMANDS) {
16+
assert.equal(
17+
COMMAND_OUTPUT_SCHEMAS[command],
18+
PREPARE_COMMAND_OUTPUT_SCHEMAS[command],
19+
`${command} is not reference-equal to the prepare module's own schema object`,
20+
);
21+
}
22+
});
23+
24+
test('the projected family map declares exactly the commands its module owns', () => {
25+
for (const command of PREPARE_COMMANDS) {
26+
assert.ok(
27+
ownerFilesForCommand(command).includes('src/commands/management/prepare.ts'),
28+
`${command} projects its output schema from this module but does not name it as its owner`,
29+
);
30+
}
31+
});

‎src/mcp/__tests__/command-tools-replay-schemas.test.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import type { ReplayCommandResult, ReplaySuiteResult } from '@agent-device/contr
44
import { ownerFilesForCommand } from '@agent-device/command-registry/owner-files';
55
import { commandSupportsSettleObservation } from '@agent-device/command-registry/registry';
66
import { WAIT_COMMAND_OUTPUT_SCHEMAS } from '../../commands/capture/wait.ts';
7+
import { PREPARE_COMMAND_OUTPUT_SCHEMAS } from '../../commands/management/prepare.ts';
78
import { DEVICE_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS } from '../../commands/management/device.ts';
89
import { PUSH_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS } from '../../commands/management/push.ts';
910
import { VIEWPORT_COMMAND_OUTPUT_SCHEMAS } from '../../commands/management/viewport.ts';
@@ -79,6 +80,7 @@ const PROJECTED_FAMILIES = [
7980
{ name: 'system', schemas: SYSTEM_COMMAND_OUTPUT_SCHEMAS },
8081
{ name: 'interaction', schemas: INTERACTION_COMMAND_OUTPUT_SCHEMAS },
8182
{ name: 'capture-wait', schemas: WAIT_COMMAND_OUTPUT_SCHEMAS },
83+
{ name: 'management-prepare', schemas: PREPARE_COMMAND_OUTPUT_SCHEMAS },
8284
{ name: 'management-device', schemas: DEVICE_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS },
8385
{ name: 'management-push', schemas: PUSH_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS },
8486
{ name: 'management-viewport', schemas: VIEWPORT_COMMAND_OUTPUT_SCHEMAS },

‎src/mcp/command-output-schemas.ts‎

Lines changed: 2 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ import {
1212
stringSchema,
1313
} from '../commands/command-input.ts';
1414
import { WAIT_COMMAND_OUTPUT_SCHEMAS } from '../commands/capture/wait.ts';
15+
import { PREPARE_COMMAND_OUTPUT_SCHEMAS } from '../commands/management/prepare.ts';
1516
import { DEVICE_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS } from '../commands/management/device.ts';
1617
import { PUSH_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS } from '../commands/management/push.ts';
1718
import { VIEWPORT_COMMAND_OUTPUT_SCHEMAS } from '../commands/management/viewport.ts';
@@ -183,65 +184,6 @@ const BASE_COMMAND_OUTPUT_SCHEMAS = {
183184
['direction'],
184185
),
185186

186-
// packages/contracts/src/prepare.ts — prepare is not MCP-exposed, but the schema stays
187-
// map-complete with CommandResultMap.
188-
prepare: objectSchema(
189-
{
190-
action: constSchema('ios-runner'),
191-
// PublicPlatform leaf, mirroring PrepareCommandResult (packages/contracts/src/prepare.ts).
192-
platform: enumSchema(PUBLIC_PLATFORMS),
193-
deviceId: stringSchema(),
194-
deviceName: stringSchema(),
195-
kind: enumSchema(DEVICE_KINDS),
196-
durationMs: numberSchema(),
197-
runner: objectSchema({}, []),
198-
cache: enumSchema(['exact', 'miss', 'external']),
199-
artifact: enumSchema(['valid', 'rebuilt']),
200-
buildMs: numberSchema(),
201-
connectMs: numberSchema(),
202-
healthCheckMs: numberSchema(),
203-
xctestrunPath: stringSchema(),
204-
recoveryReason: stringSchema(),
205-
failureReason: stringSchema(),
206-
timing: objectSchema(
207-
{
208-
totalMs: numberSchema(),
209-
additiveParts: objectSchema(
210-
{
211-
buildMs: numberSchema(),
212-
connectAfterBuildMs: numberSchema(),
213-
healthCheckMs: numberSchema(),
214-
},
215-
['connectAfterBuildMs', 'healthCheckMs'],
216-
),
217-
containment: objectSchema(
218-
{
219-
connectMs: { type: 'array', items: constSchema('buildMs') },
220-
healthCheckMs: { type: 'array', items: stringSchema() },
221-
},
222-
['healthCheckMs'],
223-
),
224-
note: stringSchema(),
225-
},
226-
['totalMs', 'additiveParts', 'containment', 'note'],
227-
),
228-
message: stringSchema(),
229-
},
230-
[
231-
'action',
232-
'platform',
233-
'deviceId',
234-
'deviceName',
235-
'kind',
236-
'durationMs',
237-
'runner',
238-
'connectMs',
239-
'healthCheckMs',
240-
'timing',
241-
'message',
242-
],
243-
),
244-
245187
// packages/contracts/src/doctor.ts
246188
doctor: objectSchema(
247189
{
@@ -304,6 +246,7 @@ const BASE_COMMAND_OUTPUT_SCHEMAS = {
304246
// a projected command then fails as TS2783 instead of quietly overriding the family's,
305247
// and this map's `satisfies` still refuses a missing `CommandResultMap` key.
306248
...WAIT_COMMAND_OUTPUT_SCHEMAS,
249+
...PREPARE_COMMAND_OUTPUT_SCHEMAS,
307250
...DEVICE_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS,
308251
...PUSH_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS,
309252
...VIEWPORT_COMMAND_OUTPUT_SCHEMAS,

0 commit comments

Comments
 (0)