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`.

Author: thymikee

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__/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,7 +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.rotate, 'function');
+  assert.equal(typeof commands.system.orientation, 'function');
   assert.equal(typeof commands.system.keyboard, 'function');
   assert.equal(typeof commands.system.clipboard, 'function');
   assert.equal(typeof commands.system.settings, 'function');

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,8 @@ const CLI_COMMAND_ALIASES: readonly CliCommandAlias[] = [
   { alias: 'tap', command: 'press' },
   { alias: 'launch', command: 'open' },
   { alias: 'relaunch', command: 'open', impliedFlags: ['relaunch'] },
+  // Deprecated: `rotate` collided with the `gesture rotate` two-finger gesture.
+  { 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,17 @@ 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 () => {

src/cli/parser/__tests__/cli-help-topics.test.ts

@@ -31,7 +31,7 @@ test('usage includes concise top-level commands', async () => {
   assert.doesNotMatch(usageText, /^  fling <up\|down\|left\|right>/m);
   assert.doesNotMatch(usageText, /^  pinch <scale> \[x\] \[y\]/m);
   assert.doesNotMatch(usageText, /^  rotate-gesture <degrees>/m);
-  assert.match(usageText, /rotate <orientation>/);
+  assert.match(usageText, /orientation <orientation>/);
   assert.match(usageText, /record start \[path\] \| record stop/);
   assert.match(usageText, /trace start <path> \| trace stop <path>/);
 });

src/cli/parser/__tests__/command-suggestions.test.ts

@@ -43,12 +43,12 @@ test('the keyboard dismiss example uses a real keyboard action', () => {
   assert.doesNotThrow(() => keyboardCliReader(['dismiss'], baseFlags));
 });
 
-// `launch`/`relaunch` (and `tap`) are true aliases normalized before the
-// unknown-command check, so they must never appear in the suggestion map —
+// `launch`/`relaunch`, `tap`, and `rotate` are true aliases normalized before
+// the unknown-command check, so they must never appear in the suggestion map —
 // a stale entry there would be dead code masking the alias.
 test('true aliases are not listed in the curated suggestion map', () => {
   const guesses = new Set(listCommandAliasSuggestionEntries().map(([guess]) => guess));
-  for (const alias of ['launch', 'relaunch', 'tap']) {
+  for (const alias of ['launch', 'relaunch', 'tap', 'rotate']) {
     assert.ok(!guesses.has(alias), `"${alias}" is a true alias and must not be a suggestion`);
   }
 });

src/cli/parser/command-suggestions.ts

@@ -10,8 +10,9 @@ import { listCliCommandNames } from '../../command-catalog.ts';
  * parse as a valid invocation of it; the registry-drift tests in
  * `src/cli/parser/__tests__/command-suggestions.test.ts` fail the build on drift.
  *
- * True aliases (`tap` -> press, `launch`/`relaunch` -> open) are normalized
- * case-insensitively in `normalizeCommandAlias` (args.ts) before the
+ * True aliases (`tap` -> press, `launch`/`relaunch` -> open, `rotate` ->
+ * orientation) are normalized case-insensitively in `normalizeCommandAlias`
+ * (args.ts) before the
  * unknown-command check runs, so they never reach this map and must not be
  * listed here. `start`/`restart` stay suggestion-only: `start` is genuinely
  * ambiguous, so a hint beats silently guessing.