refactor: remove next-major compatibility surfaces

Author: thymikee

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+- Breaking (0.21): removed aggregate performance compatibility (`perf`, `perf sample`, `perf metrics`, the `metrics` alias, optionless `client.observability.perf()`, and SDK `area: 'metrics'`). Use `perf frames`, `perf memory sample`, `perf cpu profile start|stop|report`, or `perf trace start|stop`; removed CLI and raw daemon forms fail with this migration guidance.
+- Breaking (0.21): removed legacy batch JSON steps with `positionals`/`flags`. Use `{"command":"...","input":{...}}`; rejected steps now include a concrete structured example.
+- Breaking (0.21): removed the deprecated Node client `command.rotate` wrapper and its `RotateCommandOptions` / `RotateCommandResult` exports. Use `command.orientation`; the already-removed CLI `rotate` form keeps its targeted migration error.
 - Security (MCP/AI-SDK tool surface): the operator-owned endpoint and path inputs — `daemonBaseUrl`,
   the Metro `proxyBaseUrl`, `stateDir`, `cwd`, `iosSimulatorDeviceSet`, `iosXctestrunFile`,
   `iosXctestDerivedDataPath`, `iosXctestEnvDir` — follow the credential inputs off the

packages/contracts/src/client-observability.ts

@@ -8,11 +8,8 @@ import type { NetworkIncludeMode } from '@agent-device/kernel/contracts';
 import type { AgentDeviceRequestOverrides, DeviceCommandBaseOptions } from './client-connection.ts';
 
 export type PerfOptions = DeviceCommandBaseOptions & {
-  /**
-   * Select focused performance evidence. Omitted values retain the deprecated aggregate
-   * metrics response for compatibility; prefer an explicit area.
-   */
-  area?: PerfArea;
+  /** Select focused performance evidence. */
+  area: PerfArea;
   subject?: PerfSubject;
   action?: PerfAction;
   kind?: PerfKind;

packages/contracts/src/facades/interaction.ts

@@ -144,7 +144,6 @@ export type {
   BackCommandResult,
   HomeCommandResult,
   OrientationCommandResult,
-  RotateCommandResult,
   TvRemoteCommandResult,
 } from '../navigation.ts';
 export {

packages/contracts/src/facades/observability.ts

@@ -29,6 +29,8 @@ export type { NetworkEntry } from '../network-log.ts';
 export {
   PERF_ACTION_ERROR_MESSAGE,
   PERF_ACTION_VALUES,
+  PERF_AGGREGATE_ALIAS,
+  PERF_AGGREGATE_REMOVED_ERROR_MESSAGE,
   PERF_AREA_ERROR_MESSAGE,
   PERF_AREA_VALUES,
   PERF_KIND_ERROR_MESSAGE,
@@ -40,6 +42,7 @@ export {
   isPerfArea,
   isPerfKind,
   isPerfMemoryKind,
+  isRemovedAggregatePerfToken,
   isPerfSubject,
 } from '../perf.ts';
 export type { PerfAction, PerfArea, PerfKind, PerfSubject } from '../perf.ts';

packages/contracts/src/navigation.ts

@@ -39,18 +39,6 @@ export type OrientationCommandResult = {
   message: string;
 };
 
-/**
- * @deprecated The `rotate` command was renamed to `orientation`. This is the
- * legacy response contract (`action: 'rotate'`) that shipped in v0.18/v0.19,
- * retained for existing SDK consumers until the next major version. New code
- * should use {@link OrientationCommandResult}.
- */
-export type RotateCommandResult = {
-  action: 'rotate';
-  orientation: DeviceRotation;
-  message: string;
-};
-
 /** `app-switcher` — `{ action: 'app-switcher', message: 'Opened app switcher' }`. */
 export type AppSwitcherCommandResult = {
   action: 'app-switcher';

packages/contracts/src/perf.ts

@@ -1,6 +1,7 @@
 import { defineStringEnum } from './string-enum.ts';
 
-export const PERF_AREA_VALUES = ['metrics', 'frames', 'memory', 'cpu', 'trace'] as const;
+export const PERF_AREA_VALUES = ['frames', 'memory', 'cpu', 'trace'] as const;
+export const PERF_AGGREGATE_ALIAS = 'metrics';
 export const PERF_ACTION_VALUES = ['sample', 'snapshot', 'start', 'stop', 'report'] as const;
 export const PERF_SUBJECT_VALUES = ['profile'] as const;
 export const PERF_KIND_VALUES = [
@@ -22,9 +23,11 @@ export type PerfAction = (typeof PERF_ACTION_VALUES)[number];
 export type PerfSubject = (typeof PERF_SUBJECT_VALUES)[number];
 export type PerfKind = (typeof PERF_KIND_VALUES)[number];
 
-export const PERF_AREA_ERROR_MESSAGE = 'perf area must be metrics, frames, memory, cpu, or trace';
+export const PERF_AREA_ERROR_MESSAGE = 'perf area must be frames, memory, cpu, or trace';
 export const PERF_ACTION_ERROR_MESSAGE =
   'perf action must be sample, snapshot, start, stop, or report';
+export const PERF_AGGREGATE_REMOVED_ERROR_MESSAGE =
+  'Aggregate perf was removed. Use perf frames, perf memory sample, perf cpu profile start|stop|report, or perf trace start|stop.';
 export const PERF_SUBJECT_ERROR_MESSAGE = 'perf cpu requires profile';
 export const PERF_KIND_ERROR_MESSAGE =
   'perf --kind must be xctrace, simpleperf, perfetto, android-hprof, or memgraph';
@@ -40,3 +43,10 @@ export const isPerfSubject = PERF_SUBJECTS.is;
 export const isPerfKind = PERF_KINDS.is;
 
 export const isPerfMemoryKind = PERF_MEMORY_KINDS.is;
+
+export function isRemovedAggregatePerfToken(value: unknown): boolean {
+  if (value == null) return true;
+  if (typeof value !== 'string') return false;
+  const normalized = value.toLowerCase();
+  return normalized === PERF_AGGREGATE_ALIAS || isPerfAction(normalized);
+}

scripts/__tests__/test-file-size-ratchet.test.ts

@@ -42,7 +42,7 @@ const PINNED_TEST_FILE_LINES: Readonly<Record<string, number>> = Object.freeze({
   'src/utils/__tests__/output.test.ts': 1861,
   'src/platforms/android/__tests__/snapshot.test.ts': 1445,
   'src/platforms/apple/core/__tests__/runner-client.test.ts': 1615,
-  'src/__tests__/client.test.ts': 1598,
+  'src/__tests__/client.test.ts': 1592,
   'test/integration/provider-scenarios/android-lifecycle.test.ts': 1559,
   'src/utils/__tests__/daemon-client-lifecycle.test.ts': 1414,
   'src/platforms/apple/core/__tests__/runner-command-retry.test.ts': 1327,

scripts/layering/bin-alias-fast-path.test.ts

@@ -43,7 +43,6 @@ const REGISTRY_FIXTURE = `
 import type { CliFlags } from '@agent-device/contracts/command';
 const CLI_COMMAND_ALIASES = [
   { alias: 'long-press', command: 'longpress' },
-  { alias: 'metrics', command: 'perf' },
   { alias: 'tap', command: 'press' },
   { alias: 'launch', command: 'open' },
   { alias: 'relaunch', command: 'open', impliedFlags: ['relaunch'] },
@@ -55,7 +54,6 @@ test('registryAliasTokens reads every alias property value out of the registry s
   assert.deepEqual(registryAliasTokens(REGISTRY_FIXTURE), [
     'launch',
     'long-press',
-    'metrics',
     'relaunch',
     'tap',
   ]);
@@ -269,17 +267,16 @@ const commandHelp = buildCommandUsageText(normalizeCliCommandAlias(argv[1]));
 });
 
 test('localAliasLiterals reports every requested token present as a string literal', () => {
-  // The pre-fix bin.ts shape: a hand-written table re-declaring two of the five tokens.
+  // A stale bin.ts shape with a hand-written alias table.
   const preFixBinSource = `
 function normalizeHelpTarget(command) {
   if (command === 'long-press') return 'longpress';
-  if (command === 'metrics') return 'perf';
   return command;
 }
 `;
   assert.deepEqual(
-    localAliasLiterals(preFixBinSource, ['long-press', 'metrics', 'tap', 'launch', 'relaunch']),
-    ['long-press', 'metrics'],
+    localAliasLiterals(preFixBinSource, ['long-press', 'tap', 'launch', 'relaunch']),
+    ['long-press'],
   );
 });
 
@@ -294,7 +291,7 @@ import { normalizeCliCommandAlias } from './commands/cli-command-aliases.ts';
 const commandHelp = buildCommandUsageText(normalizeCliCommandAlias(helpTarget));
 `;
   assert.deepEqual(
-    localAliasLiterals(fixedBinSource, ['long-press', 'metrics', 'tap', 'launch', 'relaunch']),
+    localAliasLiterals(fixedBinSource, ['long-press', 'tap', 'launch', 'relaunch']),
     [],
   );
 });
@@ -305,7 +302,7 @@ test('the real tree imports the resolver, calls it into buildCommandUsageText, h
   const registrySource = readFileSync(path.join(repoRoot, ALIAS_REGISTRY_FILE), 'utf8');
   const binSource = readFileSync(path.join(repoRoot, BIN_FILE), 'utf8');
   const tokens = registryAliasTokens(registrySource);
-  assert.deepEqual(tokens, ['launch', 'long-press', 'metrics', 'relaunch', 'tap']);
+  assert.deepEqual(tokens, ['launch', 'long-press', 'relaunch', 'tap']);
   const localName = aliasResolverLocalName(binSource);
   assert.equal(localName, 'normalizeCliCommandAlias');
   assert.equal(helpTargetBindingName(binSource), 'helpTarget');

scripts/layering/bin-alias-fast-path.ts

@@ -2,7 +2,7 @@
 //
 // `bin.ts`'s `--help` fast path resolves a command alias (`tap`, `launch`, …) to its canonical
 // command before looking up static help text. #1618-adjacent: bin.ts once carried its own
-// hand-written two-entry table (`long-press`, `metrics`) instead of calling the real alias
+// hand-written two-entry table (`long-press`, `launch`) instead of calling the real alias
 // registry, `commands/cli-command-aliases.ts` (five entries). The table silently fell out of
 // sync — `tap`, `launch`, `relaunch` missed the fast path entirely and paid a full CLI bootstrap
 // just to print static help text — and nothing failed, because bin.ts's own top-level dispatch
@@ -45,7 +45,7 @@
 // would otherwise let the composition read correctly while calling something else entirely, and
 // a second `helpTarget` declaration would let the resolver run on an unrelated value.
 //
-// All three were false on the pre-fix bin.ts (no import; both 'long-press' and 'metrics' present
+// All three were false on the pre-fix bin.ts (no import; both 'long-press' and 'launch' present
 // as literals; no composition to find), so the set is a real regression pin, not just a
 // description of intent.
 //

scripts/perf/scenario.ts

@@ -1,12 +1,10 @@
 import path from 'node:path';
 import type { ResolvedProfile } from './platform-profiles.ts';
 
-// A legacy-form batch step: maps through the exact documented CLI grammar.
-// `flags` uses internal CliFlags field names (e.g. snapshotInteractiveOnly).
+// A structured batch step: maps through the same command input as MCP and the Node client.
 export type BatchStepSpec = {
   command: string;
-  positionals?: string[];
-  flags?: Record<string, unknown>;
+  input: Record<string, unknown>;
 };
 
 type ScenarioStepBase = {
@@ -19,7 +17,7 @@ type ScenarioStepBase = {
 };
 
 // Discriminated on execMode so the invoker gets the right payload without `!`/`?? []`:
-// standalone carries full CLI args; batch carries one legacy batch step.
+// standalone carries full CLI args; batch carries one structured batch step.
 export type ScenarioStep =
   | (ScenarioStepBase & { execMode: 'standalone'; args: string[] })
   | (ScenarioStepBase & { execMode: 'batch'; step: BatchStepSpec; isSnapshot?: boolean });
@@ -56,32 +54,50 @@ export function buildSettingsTour(p: ResolvedProfile, ctx: StepContext): Scenari
         bat(
           'fill search',
           'fill',
-          { command: 'fill', positionals: [s.searchFieldEditable, 'general'] },
+          {
+            command: 'fill',
+            input: {
+              target: { kind: 'selector', selector: s.searchFieldEditable },
+              text: 'general',
+            },
+          },
           { freshRoot: true },
         ),
-        bat('type', 'type', { command: 'type', positionals: ['wifi'] }),
+        bat('type', 'type', { command: 'type', input: { text: 'wifi' } }),
         bat('get editable text', 'get', {
           command: 'get',
-          positionals: ['text', s.searchFieldEditable],
+          input: {
+            format: 'text',
+            target: { kind: 'selector', selector: s.searchFieldEditable },
+          },
         }),
-        bat('keyboard return', 'keyboard', { command: 'keyboard', positionals: ['return'] }),
+        bat('keyboard return', 'keyboard', { command: 'keyboard', input: { action: 'return' } }),
       ]
     : [
         // Android: tap the search entry first to reveal the editable, then type/fill it.
         bat(
           'press search field',
           'press',
-          { command: 'press', positionals: [s.searchField] },
+          {
+            command: 'press',
+            input: { target: { kind: 'selector', selector: s.searchField } },
+          },
           { freshRoot: true },
         ),
-        bat('type', 'type', { command: 'type', positionals: ['wifi'] }),
+        bat('type', 'type', { command: 'type', input: { text: 'wifi' } }),
         bat('fill search', 'fill', {
           command: 'fill',
-          positionals: [s.searchFieldEditable, 'general'],
+          input: {
+            target: { kind: 'selector', selector: s.searchFieldEditable },
+            text: 'general',
+          },
         }),
         bat('get editable text', 'get', {
           command: 'get',
-          positionals: ['text', s.searchFieldEditable],
+          input: {
+            format: 'text',
+            target: { kind: 'selector', selector: s.searchFieldEditable },
+          },
         }),
       ];
 
@@ -93,16 +109,24 @@ export function buildSettingsTour(p: ResolvedProfile, ctx: StepContext): Scenari
           bat(
             'press series (sequence)',
             'press',
-            { command: 'press', positionals: ['200', '95'], flags: { count: 2, intervalMs: 50 } },
+            {
+              command: 'press',
+              input: { target: { kind: 'point', x: 200, y: 95 }, count: 2, intervalMs: 50 },
+            },
             { freshRoot: true },
           ),
           bat(
             'swipe series (sequence)',
             'swipe',
             {
               command: 'swipe',
-              positionals: ['200', '650', '200', '450', '120'],
-              flags: { count: 2, pauseMs: 50, pattern: 'ping-pong' },
+              input: {
+                from: { x: 200, y: 650 },
+                to: { x: 200, y: 450 },
+                count: 2,
+                pauseMs: 50,
+                pattern: 'ping-pong',
+              },
             },
             { freshRoot: true },
           ),
@@ -117,27 +141,30 @@ export function buildSettingsTour(p: ResolvedProfile, ctx: StepContext): Scenari
     bat(
       'snapshot -i (root)',
       'snapshot',
-      { command: 'snapshot', flags: { snapshotInteractiveOnly: true } },
+      { command: 'snapshot', input: { interactiveOnly: true } },
       { isSnapshot: true },
     ),
-    bat('snapshot (root)', 'snapshot', { command: 'snapshot' }, { isSnapshot: true }),
+    bat('snapshot (root)', 'snapshot', { command: 'snapshot', input: {} }, { isSnapshot: true }),
 
     // --- navigate into a sub-screen from a fresh root (freshRoot resets scroll so the
     //     deep-screen row is in view), read it, then return ---
     bat(
       'press → deep screen',
       'press',
-      { command: 'press', positionals: [s.deepScreen] },
+      {
+        command: 'press',
+        input: { target: { kind: 'selector', selector: s.deepScreen } },
+      },
       { freshRoot: true },
     ),
-    bat('snapshot (deep)', 'snapshot', { command: 'snapshot' }, { isSnapshot: true }),
+    bat('snapshot (deep)', 'snapshot', { command: 'snapshot', input: {} }, { isSnapshot: true }),
     bat(
       'snapshot -i (deep)',
       'snapshot',
-      { command: 'snapshot', flags: { snapshotInteractiveOnly: true } },
+      { command: 'snapshot', input: { interactiveOnly: true } },
       { isSnapshot: true },
     ),
-    bat('back', 'back', { command: 'back' }),
+    bat('back', 'back', { command: 'back', input: {} }),
 
     // --- iOS runner series commands surfaced by PR #643 ---
     ...iosRunnerSeries,
@@ -146,26 +173,38 @@ export function buildSettingsTour(p: ResolvedProfile, ctx: StepContext): Scenari
     bat(
       'wait text',
       'wait',
-      { command: 'wait', positionals: ['text', s.anchorText, '3000'] },
+      { command: 'wait', input: { text: s.anchorText, timeoutMs: 3000 } },
       { freshRoot: true },
     ),
-    bat('find', 'find', { command: 'find', positionals: [s.anchorText] }),
-    bat('get text', 'get', { command: 'get', positionals: ['text', s.anchorLabel] }),
-    bat('is visible', 'is', { command: 'is', positionals: ['visible', s.anchorLabel] }),
+    bat('find', 'find', { command: 'find', input: { query: s.anchorText } }),
+    bat('get text', 'get', {
+      command: 'get',
+      input: {
+        format: 'text',
+        target: { kind: 'selector', selector: s.anchorLabel },
+      },
+    }),
+    bat('is visible', 'is', {
+      command: 'is',
+      input: { predicate: 'visible', selector: s.anchorLabel },
+    }),
 
     // --- text entry (platform-specific order; see textEntry above) then scroll results ---
     ...textEntry,
-    bat('scroll down', 'scroll', { command: 'scroll', positionals: ['down'] }),
+    bat('scroll down', 'scroll', { command: 'scroll', input: { direction: 'down' } }),
 
     // --- artifact-producing commands; record brackets the rest so the clip has >1s of
     //     footage (an instant start→stop makes simctl recordVideo fail to finalize) ---
     std('record start', 'record', ['record', 'start', rec, '--hide-touches']),
-    bat('screenshot', 'screenshot', { command: 'screenshot', positionals: [shot] }),
-    bat('logs mark', 'logs', { command: 'logs', positionals: ['mark', 'perf-mark'] }),
-    bat('logs clear', 'logs', { command: 'logs', positionals: ['clear'] }),
+    bat('screenshot', 'screenshot', { command: 'screenshot', input: { path: shot } }),
+    bat('logs mark', 'logs', {
+      command: 'logs',
+      input: { action: 'mark', message: 'perf-mark' },
+    }),
+    bat('logs clear', 'logs', { command: 'logs', input: { action: 'clear' } }),
     std('trace start', 'trace', ['trace', 'start', trace]),
     std('trace stop', 'trace', ['trace', 'stop']),
-    bat('perf', 'perf', { command: 'perf' }),
+    bat('perf frames', 'perf', { command: 'perf', input: { area: 'frames' } }),
     std('record stop', 'record', ['record', 'stop']),
   ];
 }