refactor: rename rotate command to orientation (rotate kept as deprecated alias) (#1252)

* refactor: rename rotate command to orientation, keep rotate as a deprecated alias

The top-level `rotate` command (device orientation: portrait/landscape) shared
a name with the `gesture rotate` two-finger rotation gesture. Rename the
orientation command to `orientation` and keep `rotate` working as a minimal,
silent CLI alias (same mechanism as `tap`->`press`) for a few versions.

The rename is applied across every layer:
- command-descriptor registry `name`, daemon dispatch handler, and the typed
  system facet (metadata/cliReader/daemonWriter/schema/output formatter)
- navigation projection + `CommandResultMap` (`OrientationCommandResult`,
  `action: 'orientation'`), client types (`OrientationCommandOptions`), and the
  runtime family (`device.system.orientation`)
- interactor + backend methods -> `setOrientation` (matching the backend's
  `setKeyboard`/`setClipboard` verb convention); Android helper
  `rotateAndroid` -> `setAndroidOrientation`
- Apple/cloud-webdriver capability keys and plugin gate
- user-facing docs (commands.md, client-api.md)

Client SDK method is `orientation` (client convention = camelCase of the
command name, matching `back`/`home`/`appSwitcher`); execution layers use the
imperative `setOrientation`.

Deliberately unchanged:
- the Swift runner wire protocol keeps `command: 'rotate'` — the runner has its
  own command namespace with no gesture collision, so renaming it would only
  risk CLI<->installed-runner version skew on physical devices
- the `DeviceRotation` value type / `parseDeviceRotation` (names the orientation
  values, no collision)

Note: `client.command.rotate` / `device.system.rotate` and the `RotateCommand*`
exported types are removed (the alias only rewrites CLI tokens); SDK consumers
must use `orientation`. The JSON `action` value changes `rotate` -> `orientation`.

* style: wrap long lines to satisfy oxfmt (orientation rename tests)

* fix: add compatibility layer for the rotate->orientation rename

Addresses review blockers on the CLI-only alias: `rotate` previously
resolved only in CLI token parsing, so command-data/RPC paths that carry
the wire command directly failed descriptor validation, and the removed
typed SDK surface broke shipped consumers.

Central command-alias boundary (was CLI-only):
- Promote `cli-command-aliases.ts` to `command-aliases.ts` as the single
  alias source, applied at each command-name ingress that bypasses the CLI
  parser: the daemon request boundary (`handleRequest`, covering replay and
  older remote clients) and the batch step readers (CLI `batch-steps.ts` and
  daemon `batch-policy.ts`). No hand-synced command tables.

Retain deprecated typed SDK surface (shipped v0.18/v0.19):
- `RotateCommandOptions` / `RotateCommandResult` type aliases (legacy
  `action: 'rotate'` contract) and `SystemRotate*` runtime types.
- `client.command.rotate` and `device.system.rotate` deprecated wrappers
  that delegate to `orientation` and restore the legacy response
  (`action: 'rotate'` / `kind: 'systemRotated'`).

ADR 0014: rename `rotate` -> `orientation` in the invalidation guidance
(lines 229, 237) so the accepted architecture doc matches the command name.

Tests: daemon-boundary rewrite, CLI+daemon batch alias resolution, and the
deprecated client/runtime wrappers preserving the legacy contract.

Live emulator evidence (emulator-5554):
- `orientation landscape-left` -> user_rotation=1
- `rotate portrait` (CLI alias) -> user_rotation=0
- batch step `{command:'rotate'}` (no CLI parser) -> user_rotation=1

* fix: preserve orientation rename compatibility

* test: stabilize orientation compatibility formatting

* style: format MCP compatibility test

* revert: drop cross-surface rotate compatibility, keep the lean rename

The rotate->orientation change is a bug fix (name collision with the
`gesture rotate` two-finger gesture), not a compatibility feature. The
cross-surface command-data compatibility added disproportionate weight
(~480 B, dominated by the alias module inlined into the batch bundle) for a
command that was only canonical for two minor versions, so shipped batch/
replay/MCP data carrying `rotate` is a rare, documentable break.

Removed:
- daemon request-boundary command normalization (`request-router.ts`)
- batch step alias resolution (`batch-policy.ts`, `cli/batch-steps.ts`)
- MCP tool-runner alias/legacy-result handling (`mcp/command-tools.ts`)
- the `command-aliases.ts` module rename and cross-surface machinery
  (reverted to `cli-command-aliases.ts`)
- the cross-surface tests

Kept (cheap, high value — prevents build breaks for typed consumers):
- CLI `rotate` alias (one line, same mechanism as `tap`/`launch`)
- deprecated `RotateCommand*` / `SystemRotate*` type aliases and the
  `client.command.rotate` / `device.system.rotate` wrappers that delegate to
  `orientation` and restore the legacy response contract

Net bundle vs main is now +473 B (was +952 B), almost all the kept SDK
wrappers plus the unavoidable longer command name.

Author: thymikee

docs/adr/0014-session-ref-frame-lifetime.md

@@ -226,15 +226,15 @@ classifying representative actions; it must not become a second prose registry:
 
 | Effect | Commands/actions |
 | --- | --- |
-| `may-invalidate` | press, click, fill, longpress, type, focus, scroll, swipe, gesture, back, home, `tv-remote`, rotate, open/relaunch, trigger/push delivery, settings changes, install/reinstall, React Native overlay dismissal, and lifecycle operations that can replace the visible surface |
+| `may-invalidate` | press, click, fill, longpress, type, focus, scroll, swipe, gesture, back, home, `tv-remote`, orientation, open/relaunch, trigger/push delivery, settings changes, install/reinstall, React Native overlay dismissal, and lifecycle operations that can replace the visible surface |
 | Conditional resolver | keyboard status preserves while dismiss/return/input invalidate; alert get/wait preserve while accept/dismiss invalidate; find reads preserve while click/fill/focus/type delegate to their leaf mutation |
 | `delegated` | batch, replay, and test/suite orchestrators; each nested leaf owns its transition |
 | `preserve` | snapshots and other observation, assertion, screenshot, recording, trace, logs, events, network inspection, performance, inventory, capability, lease, and transport-management operations unless a selected subaction directly manipulates the visible surface |
 
 Clipboard reads and writes preserve the frame because pasteboard state alone does not change element
 identity. A later paste/type action is independently invalidating.
 
-Generic routing is not an exception to the policy. `back`, `home`, `rotate`, `scroll`, `tv-remote`,
+Generic routing is not an exception to the policy. `back`, `home`, `orientation`, `scroll`, `tv-remote`,
 and `app-switcher` all reach the generic daemon leaf and must cross the same transition there when
 they act. `app-switcher` is currently projected to the daemon by a direct writer but, unlike its
 generic-routed siblings, omits an explicit daemon descriptor facet and relies on the registry's

src/__tests__/cli-help.test.ts

@@ -254,6 +254,15 @@ test('launch dispatches as a plain open without forcing a relaunch', async () =>
   assert.notEqual(result.calls[0]?.flags?.relaunch, true);
 });
 
+test('rotate dispatches as orientation (deprecated alias) with positionals preserved', async () => {
+  const result = await runCliCapture(['rotate', 'landscape-left', '--json']);
+  assert.doesNotMatch(result.stderr, /Unknown command/);
+  // Canonicalization: the daemon call must record orientation, never rotate.
+  assert.equal(result.calls.length, 1);
+  assert.equal(result.calls[0]?.command, 'orientation');
+  assert.deepEqual(result.calls[0]?.positionals, ['landscape-left']);
+});
+
 // From #1052 (credit: @vku2018): the alias must compose with the bare-ref
 // hint — `tap e3` normalizes to press, then gets the @e3 suggestion.
 test('tap with a bare ref gets the @ref hint, not an unknown-command error', async () => {

src/__tests__/client.test.ts

@@ -166,6 +166,26 @@ test('client exposes narrowed result types for closed daemon projections', async
   assert.equal(triggerResult.transport, 'deep-link');
 });
 
+test('deprecated client.command.rotate delegates to orientation and keeps the legacy action', async () => {
+  const setup = createTransport(async () => ({
+    ok: true,
+    data: {
+      action: 'orientation',
+      orientation: 'landscape-left',
+      message: 'Rotated to landscape-left',
+    },
+  }));
+  const client = createAgentDeviceClient(setup.config, { transport: setup.transport });
+
+  const result = await client.command.rotate({ orientation: 'landscape-left' });
+
+  // The wrapper sends the canonical wire command...
+  assert.equal(setup.calls.at(-1)?.command, 'orientation');
+  // ...and restores the shipped v0.18/v0.19 response contract for old consumers.
+  assert.equal(result.action, 'rotate');
+  assert.equal(result.orientation, 'landscape-left');
+});
+
 function closedProjectionResponse(command: string): DaemonResponse {
   const data = closedProjectionResponses[command];
   if (!data) throw new Error(`Unexpected command: ${command}`);

src/__tests__/contracts-schema-public.test.ts

@@ -11,7 +11,7 @@ import type {
   AppSwitcherCommandResult,
   BackCommandResult,
   HomeCommandResult,
-  RotateCommandResult,
+  OrientationCommandResult,
   TvRemoteCommandResult,
 } from '../contracts/navigation.ts';
 import type { ViewportCommandResult } from '../contracts/viewport.ts';
@@ -121,12 +121,12 @@ test('command result contracts are assignable to command result map', () => {
   } satisfies AppSwitcherCommandResult;
   const appSwitcherFromMap: CommandResult<'app-switcher'> = appSwitcher;
 
-  const rotate = {
-    action: 'rotate',
+  const orientation = {
+    action: 'orientation',
     orientation: 'portrait',
     message: 'Rotated to portrait',
-  } satisfies RotateCommandResult;
-  const rotateFromMap: CommandResult<'rotate'> = rotate;
+  } satisfies OrientationCommandResult;
+  const orientationFromMap: CommandResult<'orientation'> = orientation;
 
   const tvRemote = {
     action: 'tv-remote',
@@ -155,7 +155,7 @@ test('command result contracts are assignable to command result map', () => {
   assert.equal(backFromMap.mode, 'in-app');
   assert.equal(homeFromMap.action, 'home');
   assert.equal(appSwitcherFromMap.action, 'app-switcher');
-  assert.equal(rotateFromMap.orientation, 'portrait');
+  assert.equal(orientationFromMap.orientation, 'portrait');
   assert.equal(tvRemoteFromMap.button, 'select');
   assert.equal(clipboardFromMap.action === 'write' ? clipboardFromMap.textLength : -1, 11);
   assert.equal(

src/__tests__/runtime-public.test.ts

@@ -258,6 +258,7 @@ test('internal backend, commands, and io modules are usable', () => {
   assert.equal(typeof commands.interactions.gesture, 'function');
   assert.equal(typeof commands.system.back, 'function');
   assert.equal(typeof commands.system.home, 'function');
+  assert.equal(typeof commands.system.orientation, 'function');
   assert.equal(typeof commands.system.rotate, 'function');
   assert.equal(typeof commands.system.keyboard, 'function');
   assert.equal(typeof commands.system.clipboard, 'function');

src/agent-device-client.ts

@@ -53,8 +53,10 @@ import type {
   MaterializationReleaseOptions,
   MetroPrepareOptions,
   MetroPrepareResult,
+  OrientationCommandResult,
   PanOptions,
   FlingOptions,
+  RotateCommandResult,
   SwipeGestureOptions,
   PinchOptions,
   RotateGestureOptions,
@@ -74,7 +76,7 @@ import type { ProjectedNavigationCommandClient } from './commands/system/navigat
 import { AppError } from './kernel/errors.ts';
 
 type ProjectedSystemCommandClient = ProjectedNavigationCommandClient<InternalRequestOptions> &
-  Pick<AgentDeviceCommandClient, 'appState' | 'keyboard' | 'clipboard'>;
+  Pick<AgentDeviceCommandClient, 'appState' | 'keyboard' | 'clipboard' | 'rotate'>;
 
 export function createAgentDeviceClient(
   config: AgentDeviceClientConfig = {},
@@ -520,6 +522,17 @@ function buildProjectedSystemCommandClient(
     methods[method] = async (options = {}) =>
       await executeCommand<CommandResult<typeof command>>(command as DaemonCommandName, options);
   }
+  // Deprecated (v0.18/v0.19): `rotate` was renamed to `orientation`. Retain a
+  // thin wrapper that delegates to `orientation` and restores the legacy
+  // `action: 'rotate'` response contract for existing consumers.
+  const orientation = methods.orientation;
+  if (!orientation) {
+    throw new Error('orientation client method missing from the system command family');
+  }
+  methods.rotate = async (options = {}) => {
+    const result = (await orientation(options)) as OrientationCommandResult;
+    return { ...result, action: 'rotate' } satisfies RotateCommandResult;
+  };
   return methods as unknown as ProjectedSystemCommandClient;
 }
 

src/backend.ts

@@ -493,7 +493,7 @@ export type AgentDeviceBackend = {
     context: BackendCommandContext,
     options: BackendTvRemoteOptions,
   ): Promise<BackendActionResult>;
-  rotate?(
+  setOrientation?(
     context: BackendCommandContext,
     orientation: BackendDeviceOrientation,
   ): Promise<BackendActionResult>;

src/cli-command-aliases.ts

@@ -16,6 +16,9 @@ const CLI_COMMAND_ALIASES: readonly CliCommandAlias[] = [
   { alias: 'tap', command: 'press' },
   { alias: 'launch', command: 'open' },
   { alias: 'relaunch', command: 'open', impliedFlags: ['relaunch'] },
+  // Deprecated: `rotate` was renamed to `orientation` (it collided with the
+  // `gesture rotate` two-finger gesture). Kept working at the CLI for a few versions.
+  { alias: 'rotate', command: 'orientation' },
 ];
 
 const aliasByToken: ReadonlyMap<string, CliCommandAlias> = new Map(

src/cli/parser/__tests__/args-parse-interaction.test.ts

@@ -305,9 +305,15 @@ test('parseArgs supports trigger-app-event payload argument', () => {
   assert.deepEqual(parsed.positionals, ['screenshot_taken', '{"source":"qa"}']);
 });
 
-test('parseArgs accepts rotate orientation aliases', () => {
+test('parseArgs accepts the orientation command', () => {
+  const parsed = parseArgs(['orientation', 'left'], { strictFlags: true });
+  assert.equal(parsed.command, 'orientation');
+  assert.deepEqual(parsed.positionals, ['left']);
+});
+
+test('parseArgs normalizes the deprecated rotate alias to orientation', () => {
   const parsed = parseArgs(['rotate', 'left'], { strictFlags: true });
-  assert.equal(parsed.command, 'rotate');
+  assert.equal(parsed.command, 'orientation');
   assert.deepEqual(parsed.positionals, ['left']);
 });
 

src/cli/parser/__tests__/cli-help-command-usage.test.ts

@@ -372,11 +372,23 @@ test('keyboard command usage is documented', async () => {
   );
 });
 
-test('rotate command usage is documented', async () => {
+test('orientation command usage is documented', async () => {
+  const help = await usageForCommand('orientation');
+  if (help === null) throw new Error('Expected command help text');
+  assert.match(
+    help,
+    /orientation <portrait\|portrait-upside-down\|landscape-left\|landscape-right>/,
+  );
+  assert.match(help, /Set device orientation on iOS and Android/);
+});
+
+test('deprecated rotate alias resolves to orientation usage', async () => {
   const help = await usageForCommand('rotate');
   if (help === null) throw new Error('Expected command help text');
-  assert.match(help, /rotate <portrait\|portrait-upside-down\|landscape-left\|landscape-right>/);
-  assert.match(help, /Rotate device orientation on iOS and Android/);
+  assert.match(
+    help,
+    /orientation <portrait\|portrait-upside-down\|landscape-left\|landscape-right>/,
+  );
 });
 
 test('settings usage documents canonical faceid states', async () => {