diff --git a/packages/command-registry/src/flag-definitions-target.ts b/packages/command-registry/src/flag-definitions-target.ts index f9995de54a..f48ae8072d 100644 --- a/packages/command-registry/src/flag-definitions-target.ts +++ b/packages/command-registry/src/flag-definitions-target.ts @@ -217,7 +217,8 @@ export const TARGET_FLAG_DEFINITIONS: readonly FlagDefinition[] = [ type: 'enum', enumValues: ['auto', 'react-native', 'expo', 'repack'], usageLabel: '--metro-kind auto|react-native|expo|repack', - usageDescription: 'metro prepare: detect or force the React Native dev-server launcher kind', + usageDescription: + 'connect: detect or force the React Native dev-server launcher kind for deferred Metro preparation. `metro prepare` reads --kind instead', projectConfig: false, recorded: false, }, diff --git a/packages/command-registry/src/flag-groups.ts b/packages/command-registry/src/flag-groups.ts index b07bb93950..8459705923 100644 --- a/packages/command-registry/src/flag-groups.ts +++ b/packages/command-registry/src/flag-groups.ts @@ -19,7 +19,6 @@ export const SELECTOR_SNAPSHOT_FLAGS = flagKeys('snapshotDepth', 'snapshotScope' export const METRO_PREPARE_FLAGS = flagKeys( 'metroProjectRoot', 'kind', - 'metroKind', 'metroPublicBaseUrl', 'metroProxyBaseUrl', 'metroBearerToken', @@ -33,6 +32,10 @@ export const METRO_PREPARE_FLAGS = flagKeys( 'metroNoInstallDeps', ); +// The `--metro-*` connect hint family `connect` saves for deferred Metro preparation. `metro +// prepare` reads `--kind` and not the `--metro-kind` alias, so only connect allows this key. +export const CONNECT_METRO_HINT_FLAGS = flagKeys('metroKind'); + export const METRO_RELOAD_FLAGS = flagKeys('metroHost', 'metroPort', 'bundleUrl'); // The device spec a proxy lease is allocated by; the commands that allocate a proxy lease take it. export const LEASE_DEVICE_SPEC_FLAGS = flagKeys( diff --git a/packages/command-surface/src/capture/diff.ts b/packages/command-surface/src/capture/diff.ts index 7e397dff04..59dcadecba 100644 --- a/packages/command-surface/src/capture/diff.ts +++ b/packages/command-surface/src/capture/diff.ts @@ -69,7 +69,6 @@ const diffCommandDescription = const diffCommandMetadata = defineFieldCommandMetadata(DIFF_COMMAND_NAME, diffCommandDescription, { kind: requiredField(jsonSchemaField<'snapshot'>({ type: 'string', const: 'snapshot' })), - out: stringField(), interactiveOnly: booleanField(), depth: integerField(), scope: stringField(), @@ -101,7 +100,6 @@ export const diffCliReader: CliReader = (positionals, flags) => { return { ...commonInputFromFlags(flags), kind: 'snapshot', - out: flags.out, interactiveOnly: flags.snapshotInteractiveOnly, depth: flags.snapshotDepth, scope: flags.snapshotScope, @@ -120,7 +118,7 @@ export const diffCommandFacet = defineCommandFacet({ summary: 'Diff snapshot or screenshot', searchHint: 'visual regression baseline', cliDetail: - 'Screenshot --threshold is a per-pixel RGB tolerance: 0 requires exact colors and 1 ignores color differences; the current image scales proportionally to the baseline width and aligns top-left. Scaled height rounds to the nearest pixel (minimum 1). Extra or missing bottom rows always count as differences, even at threshold 1. The originals remain unchanged. When dimensions differ, normalization metadata reports original, scaled and compared sizes; region coordinates use comparison pixels. Both screenshot inputs are decoded from their bytes, so a baseline or current image may be PNG or JPEG, and the diff image is always PNG. JPEG is lossy, so keep --threshold above 0 whenever either input is JPEG. Live iOS simulator screenshot diffs normalize status-bar chrome by default; use screenshot --normalize-status-bar when capturing reusable baselines. Use --screen-mask black for a live iOS simulator capture with a black screen outline, and use the same option when creating its baseline. --screen-mask is refused when current.png is supplied; saved images are compared unchanged.', + 'Snapshot comparisons report text only: --out is the diff PNG path screenshot comparisons write, and `diff snapshot` never writes a file. Screenshot --threshold is a per-pixel RGB tolerance: 0 requires exact colors and 1 ignores color differences; the current image scales proportionally to the baseline width and aligns top-left. Scaled height rounds to the nearest pixel (minimum 1). Extra or missing bottom rows always count as differences, even at threshold 1. The originals remain unchanged. When dimensions differ, normalization metadata reports original, scaled and compared sizes; region coordinates use comparison pixels. Both screenshot inputs are decoded from their bytes, so a baseline or current image may be PNG or JPEG, and the diff image is always PNG. JPEG is lossy, so keep --threshold above 0 whenever either input is JPEG. Live iOS simulator screenshot diffs normalize status-bar chrome by default; use screenshot --normalize-status-bar when capturing reusable baselines. Use --screen-mask black for a live iOS simulator capture with a black screen outline, and use the same option when creating its baseline. --screen-mask is refused when current.png is supplied; saved images are compared unchanged.', }, metadata: diffCommandMetadata, run: (client, input) => client.capture.diff(input), diff --git a/packages/command-surface/src/capture/index.test.ts b/packages/command-surface/src/capture/index.test.ts index 308a763174..5080425c9b 100644 --- a/packages/command-surface/src/capture/index.test.ts +++ b/packages/command-surface/src/capture/index.test.ts @@ -102,13 +102,13 @@ describe('capture command interface', () => { }); test('reads diff snapshot input only', () => { - expect( - diffCliReader(['snapshot'], flags({ snapshotDepth: 4, out: './diff.json' })), - ).toMatchObject({ + const input = diffCliReader(['snapshot'], flags({ snapshotDepth: 4, out: './diff.json' })); + expect(input).toMatchObject({ kind: 'snapshot', depth: 4, - out: './diff.json', }); + // `diff snapshot` never writes a file, so the reader carries no out for it. + expect(input).not.toHaveProperty('out'); expectInvalidArgs(() => diffCliReader(['screenshot'], flags()), 'Only diff snapshot'); }); diff --git a/packages/command-surface/src/metro/index.test.ts b/packages/command-surface/src/metro/index.test.ts index 764d115950..31f994ec33 100644 --- a/packages/command-surface/src/metro/index.test.ts +++ b/packages/command-surface/src/metro/index.test.ts @@ -87,6 +87,23 @@ describe('metro command interface', () => { }); }); + test('prepare reads --kind and not the retired --metro-kind alias', () => { + expect( + metroCliReader( + ['prepare'], + flags({ metroPublicBaseUrl: 'https://public.example.test', kind: 'expo' }), + ), + ).toMatchObject({ kind: 'expo' }); + // The parser refuses --metro-kind for metro, so a value that reaches the reader from + // connect's saved profile must not leak into a prepare request either. + expect( + metroCliReader( + ['prepare'], + flags({ metroPublicBaseUrl: 'https://public.example.test', metroKind: 'expo' }), + ).kind, + ).toBeUndefined(); + }); + test('rejects invalid metro input', () => { expectInvalidArgs(() => metroCliReader(['start'], flags()), 'metro requires a subcommand'); expectInvalidArgs( diff --git a/packages/command-surface/src/metro/index.ts b/packages/command-surface/src/metro/index.ts index 2487f8294c..3ee49e91eb 100644 --- a/packages/command-surface/src/metro/index.ts +++ b/packages/command-surface/src/metro/index.ts @@ -108,7 +108,7 @@ export const metroCliReader: CliReader = (positionals, flags) => { return { action, projectRoot: flags.metroProjectRoot, - kind: readMetroPrepareKind(flags.kind ?? flags.metroKind), + kind: readMetroPrepareKind(flags.kind), port: flags.metroPreparePort, listenHost: flags.metroListenHost, statusHost: flags.metroStatusHost, diff --git a/packages/command-surface/src/schema/command-overrides.ts b/packages/command-surface/src/schema/command-overrides.ts index 1a9706ff86..e2f6f1d9e2 100644 --- a/packages/command-surface/src/schema/command-overrides.ts +++ b/packages/command-surface/src/schema/command-overrides.ts @@ -4,6 +4,7 @@ import type { LocalCliCommandName } from '@agent-device/command-registry/catalog import type { CommandSchema } from '@agent-device/command-registry/command-schema'; import { COMMON_COMMAND_SUPPORTED_FLAG_KEYS, + CONNECT_METRO_HINT_FLAGS, LEASE_DEVICE_SPEC_FLAGS, METRO_PREPARE_FLAGS, } from '@agent-device/command-registry/flag-groups'; @@ -126,6 +127,7 @@ const SCHEMA_ONLY_CLI_COMMAND_SCHEMAS = { 'platform', 'device', ...METRO_PREPARE_FLAGS, + ...CONNECT_METRO_HINT_FLAGS, 'launchUrl', ], }, diff --git a/packages/command-surface/src/schema/option-schema.test.ts b/packages/command-surface/src/schema/option-schema.test.ts index 0f23a39e99..ad230400bf 100644 --- a/packages/command-surface/src/schema/option-schema.test.ts +++ b/packages/command-surface/src/schema/option-schema.test.ts @@ -106,6 +106,9 @@ test('isFlagSupportedForCommand consults option schema support map', () => { assert.equal(isFlagSupportedForCommand('delayMs', 'type'), true); assert.equal(isFlagSupportedForCommand('delayMs', 'fill'), true); assert.equal(isFlagSupportedForCommand('delayMs', 'press'), false); + // `metro prepare` reads --kind; --metro-kind belongs to connect's hint family only. + assert.equal(isFlagSupportedForCommand('metroKind', 'metro'), false); + assert.equal(isFlagSupportedForCommand('metroKind', 'connect'), true); }); test('option schema parses enum options from env/config sources', () => { diff --git a/packages/contracts/src/client-capture.ts b/packages/contracts/src/client-capture.ts index 047f3c9bce..1685882201 100644 --- a/packages/contracts/src/client-capture.ts +++ b/packages/contracts/src/client-capture.ts @@ -145,7 +145,6 @@ export type CaptureScreenshotResult = ScreenshotResultData & { export type CaptureDiffOptions = DeviceCommandBaseOptions & Pick & { kind: 'snapshot'; - out?: string; }; export type CaptureAuditOptions = DeviceCommandBaseOptions; diff --git a/src/__tests__/cli-client-commands.test.ts b/src/__tests__/cli-client-commands.test.ts index 4ab0fd8cc3..15ab530ecd 100644 --- a/src/__tests__/cli-client-commands.test.ts +++ b/src/__tests__/cli-client-commands.test.ts @@ -169,7 +169,7 @@ test('metro prepare forwards normalized options to client.metro.prepare', async runId: 'run-1', leaseId: 'lease-1', metroPreparePort: 9090, - metroKind: 'expo', + kind: 'expo', metroRuntimeFile: './.agent-device/metro-runtime.json', metroNoReuseExisting: true, metroNoInstallDeps: true, diff --git a/src/cli/parser/__tests__/args-validation.test.ts b/src/cli/parser/__tests__/args-validation.test.ts index e768650d3e..f3f07fbcf9 100644 --- a/src/cli/parser/__tests__/args-validation.test.ts +++ b/src/cli/parser/__tests__/args-validation.test.ts @@ -32,6 +32,41 @@ test('parseArgs rejects invalid record --fps range', () => { ); }); +test('parseArgs refuses the --metro-kind alias on metro prepare and keeps it on connect', () => { + // `metro prepare` reads --kind only. --metro-kind stays a connect hint: it names the + // launcher kind deferred Metro preparation runs with, so connect still parses it. + assert.throws( + () => + parseArgs( + [ + 'metro', + 'prepare', + '--public-base-url', + 'https://sandbox.example.test', + '--metro-kind', + 'expo', + ], + { strictFlags: true }, + ), + (error: unknown) => + error instanceof AppError && + error.code === 'INVALID_ARGS' && + error.message === 'Flag --metro-kind is not supported for command metro.', + ); + + const prepare = parseArgs( + ['metro', 'prepare', '--public-base-url', 'https://sandbox.example.test', '--kind', 'expo'], + { strictFlags: true }, + ); + assert.equal(prepare.command, 'metro'); + assert.deepEqual(prepare.positionals, ['prepare']); + assert.equal(prepare.flags.kind, 'expo'); + + const connect = parseArgs(['connect', 'proxy', '--metro-kind', 'expo'], { strictFlags: true }); + assert.equal(connect.command, 'connect'); + assert.equal(connect.flags.metroKind, 'expo'); +}); + test('parseArgs refuses a record option the chosen action never reads', () => { const cases: Array<[string[], string]> = [ [ diff --git a/src/mcp/__tests__/command-tools-input-docs.test.ts b/src/mcp/__tests__/command-tools-input-docs.test.ts index 84a5e159c8..a20e2da12e 100644 --- a/src/mcp/__tests__/command-tools-input-docs.test.ts +++ b/src/mcp/__tests__/command-tools-input-docs.test.ts @@ -23,7 +23,6 @@ const UNDESCRIBED_TOOL_INPUTS = new Set([ 'diff.depth', 'diff.interactiveOnly', 'diff.kind', - 'diff.out', 'diff.raw', 'diff.scope', 'events.cursor', diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md index 181d75696c..2fd576a840 100644 --- a/website/docs/docs/commands.md +++ b/website/docs/docs/commands.md @@ -2290,7 +2290,6 @@ agent-device metro reload [--metro-host ] [--metro-port ] [--bundle- | --- | --- | | `--project-root ` | metro prepare: React Native project root (default: cwd) | | `--kind ` | Kind selector for commands that support it, such as metro prepare or perf artifact collectors | -| `--metro-kind auto\|react-native\|expo\|repack` | metro prepare: detect or force the React Native dev-server launcher kind | | `--public-base-url ` | metro prepare: public base URL used for direct dev-server bundle hints | | `--proxy-base-url ` | metro prepare: optional bridge origin for remote dev-server access | | `--bearer-token ` | metro prepare: host bridge bearer token (or AGENT_DEVICE_METRO_BEARER_TOKEN; falls back to AGENT_DEVICE_DAEMON_AUTH_TOKEN) |