refactor: colocate native platform sources under android/, apple/, linux/

.fallowrc.json

@@ -28,7 +28,7 @@
     "examples/test-app/**",
     "scripts/perf/**",
     "scripts/layering/**",
-    "apple-runner/AgentDeviceRunner/AgentDeviceRunnerUITests.xctestplan",
+    "apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests.xctestplan",
     "scripts/write-xcuitest-cache-metadata.mjs"
   ],
   "ignoreDependencies": ["@theme"],

.gitattributes

@@ -1 +1 @@
-android-snapshot-helper/debug.keystore binary
+android/snapshot-helper/debug.keystore binary

.github/actions/setup-apple-replay/action.yml

@@ -52,7 +52,7 @@ runs:
       id: source-hash
       run: |
         set -euo pipefail
-        echo "value=${{ hashFiles('apple-runner/**', 'scripts/build-xcuitest-apple.sh', 'scripts/patch-xcuitest-runner-icon.ts', 'scripts/write-xcuitest-cache-metadata.mjs', 'src/platforms/ios/apple-runner-platform.ts', 'src/platforms/ios/runner-icon.ts', 'src/platforms/ios/runner-xctestrun.ts', 'src/platforms/ios/runner-xctestrun-products.ts', '.github/actions/setup-apple-replay/action.yml', 'package.json', 'pnpm-lock.yaml') }}" >> "$GITHUB_OUTPUT"
+        echo "value=${{ hashFiles('apple/runner/**', 'scripts/build-xcuitest-apple.sh', 'scripts/patch-xcuitest-runner-icon.ts', 'scripts/write-xcuitest-cache-metadata.mjs', 'src/platforms/ios/apple-runner-platform.ts', 'src/platforms/ios/runner-icon.ts', 'src/platforms/ios/runner-xctestrun.ts', 'src/platforms/ios/runner-xctestrun-products.ts', '.github/actions/setup-apple-replay/action.yml', 'package.json', 'pnpm-lock.yaml') }}" >> "$GITHUB_OUTPUT"
       shell: bash
 
     - name: Cache replay prebuilt

.github/workflows/ci.yml

@@ -32,7 +32,7 @@ jobs:
 
       - name: Disallow trailing commas before closing parenthesis in Swift
         run: |
-          if rg -nU --glob '*.swift' ',\s*\n\s*\)' apple-runner; then
+          if rg -nU --glob '*.swift' ',\s*\n\s*\)' apple/runner; then
             echo "Found trailing commas before ')' in Swift files. This syntax requires Swift 6.1+ and breaks older Xcode toolchains."
             exit 1
           fi

.github/workflows/linux.yml

@@ -97,7 +97,7 @@ jobs:
           echo "=== AT-SPI2 Python bindings ==="
           python3 -c "import gi; gi.require_version('Atspi', '2.0'); from gi.repository import Atspi; print('OK')"
           echo "=== AT-SPI2 tree dump (quick test) ==="
-          python3 src/platforms/linux/atspi-dump.py --surface desktop --max-nodes 5 | python3 -m json.tool | head -20 || echo "::warning::AT-SPI2 tree dump returned no nodes (expected before any app is launched)"
+          python3 linux/atspi-dump.py --surface desktop --max-nodes 5 | python3 -m json.tool | head -20 || echo "::warning::AT-SPI2 tree dump returned no nodes (expected before any app is launched)"
           echo "=== xdotool ==="
           xdotool version
 

.gitignore

@@ -34,9 +34,9 @@ xcuserdata/
 *.xctestrun
 *.xcarchive
 .skillgym-results/
-android-snapshot-helper/build/
-android-snapshot-helper/dist/
-android-multitouch-helper/build/
-android-multitouch-helper/dist/
-android-ime-helper/build/
-android-ime-helper/dist/
+android/snapshot-helper/build/
+android/snapshot-helper/dist/
+android/multitouch-helper/build/
+android/multitouch-helper/dist/
+android/ime-helper/build/
+android/ime-helper/dist/

.worktreeinclude

@@ -8,10 +8,10 @@ examples/test-app/.expo/
 .build/
 .swiftpm/
 DerivedData/
-android-snapshot-helper/build/
-android-snapshot-helper/dist/
-android-multitouch-helper/build/
-android-multitouch-helper/dist/
+android/snapshot-helper/build/
+android/snapshot-helper/dist/
+android/multitouch-helper/build/
+android/multitouch-helper/dist/
 
 # Tool caches
 .fallow/

android-snapshot-helper/README.md → android/snapshot-helper/README.md

@@ -20,7 +20,7 @@ sh ./scripts/build-android-snapshot-helper.sh "$VERSION" .tmp/android-snapshot-h
 
 The build uses Android SDK command-line tools directly. It expects `ANDROID_HOME` or
 `ANDROID_SDK_ROOT` to point at an SDK with `platforms/android-36` and matching build tools.
-`pnpm prepack` builds the npm-bundled helper into `android-snapshot-helper/dist`; npm users get
+`pnpm prepack` builds the npm-bundled helper into `android/snapshot-helper/dist`; npm users get
 that APK in the package and the first helper-backed `snapshot` installs it automatically when
 missing or outdated.
 

apple-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTapPointPolicy.swift → apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTapPointPolicy.swift

@@ -53,7 +53,8 @@ extension RunnerTests {
     let fixtureURL = URL(fileURLWithPath: #filePath)
       .deletingLastPathComponent() // AgentDeviceRunnerUITests
       .deletingLastPathComponent() // AgentDeviceRunner
-      .deletingLastPathComponent() // apple-runner
+      .deletingLastPathComponent() // runner
+      .deletingLastPathComponent() // apple
       .deletingLastPathComponent() // repo root
       .appendingPathComponent("contracts")
       .appendingPathComponent("fixtures")

apple-runner/README.md → apple/runner/README.md

@@ -15,7 +15,7 @@ Current internal runner for iOS, tvOS, and macOS desktop automation.
 Protocol and maintenance references:
 
 - Protocol overview: [`RUNNER_PROTOCOL.md`](RUNNER_PROTOCOL.md)
-- TypeScript client: [`../src/platforms/apple/core/runner/runner-client.ts`](../src/platforms/apple/core/runner/runner-client.ts)
+- TypeScript client: [`../../src/platforms/apple/core/runner/runner-client.ts`](../../src/platforms/apple/core/runner/runner-client.ts)
 - Swift wire models: [`AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift)
 
 ## UITest Runner File Map
@@ -46,7 +46,7 @@ serialize reliably. In those cases interactive snapshots may return a sparse roo
 full snapshots preserve the XCTest error. A penalized simulator can recover through private AX;
 physical devices use a short XCTest probe because no non-XCTest semantic backend is available
 there. See
-[`../docs/adr/0004-ios-snapshot-backend-strategy.md`](../docs/adr/0004-ios-snapshot-backend-strategy.md)
+[`../../docs/adr/0004-ios-snapshot-backend-strategy.md`](../../docs/adr/0004-ios-snapshot-backend-strategy.md)
 for the backend boundary and future simulator AX-service direction.
 
 ## Protocol Notes

apple-runner/RUNNER_PROTOCOL.md → apple/runner/RUNNER_PROTOCOL.md

@@ -41,7 +41,7 @@ Examples:
 
 The current command names are defined in:
 
-- [`../src/platforms/apple/core/runner/runner-client.ts`](../src/platforms/apple/core/runner/runner-client.ts)
+- [`../../src/platforms/apple/core/runner/runner-client.ts`](../../src/platforms/apple/core/runner/runner-client.ts)
 - [`AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift)
 
 ## Response Shape

package.json

@@ -90,16 +90,16 @@
     "build:xcuitest:visionos:clean": "pnpm clean:xcuitest:visionos && pnpm build:xcuitest:visionos",
     "build:android-snapshot-helper": "sh ./scripts/build-android-snapshot-helper.sh $(node -p \"require('./package.json').version\") .tmp/android-snapshot-helper",
     "package:android-snapshot-helper": "sh ./scripts/package-android-snapshot-helper.sh $(node -p \"require('./package.json').version\") v$(node -p \"require('./package.json').version\") .tmp/android-snapshot-helper",
-    "package:android-snapshot-helper:npm": "rm -rf android-snapshot-helper/dist && sh ./scripts/package-android-snapshot-helper.sh $(node -p \"require('./package.json').version\") v$(node -p \"require('./package.json').version\") android-snapshot-helper/dist",
+    "package:android-snapshot-helper:npm": "rm -rf android/snapshot-helper/dist && sh ./scripts/package-android-snapshot-helper.sh $(node -p \"require('./package.json').version\") v$(node -p \"require('./package.json').version\") android/snapshot-helper/dist",
     "package:apple-runner:npm": "node scripts/package-apple-runner-source.mjs",
     "build:android-multitouch-helper": "sh ./scripts/build-android-multitouch-helper.sh $(node -p \"require('./package.json').version\") .tmp/android-multitouch-helper",
     "package:android-multitouch-helper": "sh ./scripts/package-android-multitouch-helper.sh $(node -p \"require('./package.json').version\") .tmp/android-multitouch-helper",
-    "package:android-multitouch-helper:npm": "rm -rf android-multitouch-helper/dist && sh ./scripts/package-android-multitouch-helper.sh $(node -p \"require('./package.json').version\") android-multitouch-helper/dist",
+    "package:android-multitouch-helper:npm": "rm -rf android/multitouch-helper/dist && sh ./scripts/package-android-multitouch-helper.sh $(node -p \"require('./package.json').version\") android/multitouch-helper/dist",
     "build:android": "pnpm package:android-snapshot-helper:npm && pnpm package:android-multitouch-helper:npm && pnpm package:android-ime-helper:npm",
     "build:android-ime-helper": "sh ./scripts/build-android-ime-helper.sh $(node -p \"require('./package.json').version\") .tmp/android-ime-helper",
     "package:android-ime-helper": "sh ./scripts/package-android-ime-helper.sh $(node -p \"require('./package.json').version\") .tmp/android-ime-helper",
-    "package:android-ime-helper:npm": "rm -rf android-ime-helper/dist && sh ./scripts/package-android-ime-helper.sh $(node -p \"require('./package.json').version\") android-ime-helper/dist",
-    "build:macos-helper": "swift build -c release --package-path macos-helper",
+    "package:android-ime-helper:npm": "rm -rf android/ime-helper/dist && sh ./scripts/package-android-ime-helper.sh $(node -p \"require('./package.json').version\") android/ime-helper/dist",
+    "build:macos-helper": "swift build -c release --package-path apple/macos-helper",
     "build:all": "pnpm build:node && pnpm build:xcuitest",
     "ad": "node bin/agent-device.mjs",
     "bench:help-conformance": "node scripts/help-conformance-bench.mjs",
@@ -163,18 +163,18 @@
   "files": [
     "bin",
     "dist",
-    "macos-helper",
-    "!macos-helper/**/.build",
-    "android-snapshot-helper/dist",
-    "!android-snapshot-helper/dist/*.idsig",
-    "!android-snapshot-helper/README.md",
-    "android-multitouch-helper/dist",
-    "!android-multitouch-helper/dist/*.idsig",
-    "!android-multitouch-helper/README.md",
-    "android-ime-helper/dist",
-    "!android-ime-helper/dist/*.idsig",
-    "!android-ime-helper/README.md",
-    "src/platforms/linux/atspi-dump.py",
+    "apple/macos-helper",
+    "!apple/macos-helper/**/.build",
+    "android/snapshot-helper/dist",
+    "!android/snapshot-helper/dist/*.idsig",
+    "!android/snapshot-helper/README.md",
+    "android/multitouch-helper/dist",
+    "!android/multitouch-helper/dist/*.idsig",
+    "!android/multitouch-helper/README.md",
+    "android/ime-helper/dist",
+    "!android/ime-helper/dist/*.idsig",
+    "!android/ime-helper/README.md",
+    "linux/atspi-dump.py",
     "skills",
     "server.json",
     "smithery.yaml",

scripts/build-android-ime-helper.sh

@@ -9,7 +9,7 @@ fi
 VERSION="$1"
 OUTPUT_DIR="$2"
 PROJECT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)"
-HELPER_DIR="$PROJECT_DIR/android-ime-helper"
+HELPER_DIR="$PROJECT_DIR/android/ime-helper"
 PACKAGE_NAME="com.callstack.agentdevice.imehelper"
 MIN_SDK=23
 TARGET_SDK=36
@@ -49,7 +49,7 @@ BUILD_DIR="$HELPER_DIR/build"
 CLASSES_DIR="$BUILD_DIR/classes"
 DEX_DIR="$BUILD_DIR/dex"
 RES_COMPILED_DIR="$BUILD_DIR/res-compiled"
-KEYSTORE="$PROJECT_DIR/android-snapshot-helper/debug.keystore"
+KEYSTORE="$PROJECT_DIR/android/snapshot-helper/debug.keystore"
 UNSIGNED_APK="$BUILD_DIR/helper-unsigned.apk"
 ALIGNED_APK="$BUILD_DIR/helper-aligned.apk"
 APK_PATH="$OUTPUT_DIR/$APK_BASENAME"

scripts/build-android-multitouch-helper.sh

@@ -9,7 +9,7 @@ fi
 VERSION="$1"
 OUTPUT_DIR="$2"
 PROJECT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)"
-HELPER_DIR="$PROJECT_DIR/android-multitouch-helper"
+HELPER_DIR="$PROJECT_DIR/android/multitouch-helper"
 PACKAGE_NAME="com.callstack.agentdevice.multitouchhelper"
 MIN_SDK=23
 TARGET_SDK=36
@@ -49,7 +49,7 @@ BUILD_DIR="$HELPER_DIR/build"
 CLASSES_DIR="$BUILD_DIR/classes"
 TEST_CLASSES_DIR="$BUILD_DIR/test-classes"
 DEX_DIR="$BUILD_DIR/dex"
-KEYSTORE="$PROJECT_DIR/android-snapshot-helper/debug.keystore"
+KEYSTORE="$PROJECT_DIR/android/snapshot-helper/debug.keystore"
 UNSIGNED_APK="$BUILD_DIR/helper-unsigned.apk"
 ALIGNED_APK="$BUILD_DIR/helper-aligned.apk"
 APK_PATH="$OUTPUT_DIR/$APK_BASENAME"

scripts/build-android-snapshot-helper.sh

@@ -9,7 +9,7 @@ fi
 VERSION="$1"
 OUTPUT_DIR="$2"
 PROJECT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)"
-HELPER_DIR="$PROJECT_DIR/android-snapshot-helper"
+HELPER_DIR="$PROJECT_DIR/android/snapshot-helper"
 PACKAGE_NAME="com.callstack.agentdevice.snapshothelper"
 MIN_SDK=23
 TARGET_SDK=36

scripts/build-xcuitest-apple.sh

@@ -2,7 +2,7 @@
 set -eu
 
 PLATFORM="${AGENT_DEVICE_XCUITEST_PLATFORM:-}"
-PROJECT_PATH="apple-runner/AgentDeviceRunner/AgentDeviceRunner.xcodeproj"
+PROJECT_PATH="apple/runner/AgentDeviceRunner/AgentDeviceRunner.xcodeproj"
 SCHEME="AgentDeviceRunner"
 DEFAULT_IOS_RUNNER_APP_BUNDLE_ID="com.callstack.agentdevice.runner"
 

scripts/check-affected/model.test.ts

@@ -75,13 +75,13 @@ test('android-adb stub test delegates project ownership to Vitest', () => {
 });
 
 test('Swift runner change selects the swift-runner build', () => {
-  assert.deepEqual(ids(['apple-runner/Sources/Runner/Main.swift']), ['swift-runner']);
+  assert.deepEqual(ids(['apple/runner/Sources/Runner/Main.swift']), ['swift-runner']);
   assert.ok(ids(['src/platforms/apple/core/runner/Support.swift']).includes('swift-runner'));
 });
 
 test('Android helper change selects the android-helpers build', () => {
-  assert.deepEqual(ids(['android-snapshot-helper/src/Main.kt']), ['android-helpers']);
-  assert.deepEqual(ids(['android-multitouch-helper/build.gradle']), ['android-helpers']);
+  assert.deepEqual(ids(['android/snapshot-helper/src/Main.kt']), ['android-helpers']);
+  assert.deepEqual(ids(['android/multitouch-helper/build.gradle']), ['android-helpers']);
 });
 
 test('MCP metadata change selects the mcp-metadata check', () => {

scripts/check-affected/model.ts

@@ -244,20 +244,21 @@ const BUILD_OWNERSHIP: ReadonlyArray<{
     check: 'swift-runner',
     rule: 'own:swift',
     detail: 'Swift runner sources require the XCUITest build',
-    owns: (file) => file.startsWith('apple-runner/') || file.endsWith('.swift'),
+    owns: (file) => file.startsWith('apple/runner/') || file.endsWith('.swift'),
   },
   {
     check: 'android-helpers',
     rule: 'own:android-helpers',
     detail: 'Android helper packages have their own build',
     owns: (file) =>
-      file.startsWith('android-snapshot-helper/') || file.startsWith('android-multitouch-helper/'),
+      file.startsWith('android/snapshot-helper/') ||
+      file.startsWith('android/multitouch-helper/'),
   },
   {
     check: 'macos-helper',
     rule: 'own:macos-helper',
     detail: 'macOS helper is a separate Swift package build',
-    owns: (file) => file.startsWith('macos-helper/'),
+    owns: (file) => file.startsWith('apple/macos-helper/'),
   },
   {
     check: 'mcp-metadata',

scripts/package-apple-runner-source.mjs

@@ -4,8 +4,16 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const UNIT_TEST_CONDITION = 'AGENT_DEVICE_RUNNER_UNIT_TESTS';
-const SOURCE_DIR = path.join('apple-runner');
-const OUTPUT_DIR = path.join('dist', 'apple-runner');
+const SOURCE_DIR = path.join('apple', 'runner');
+const OUTPUT_DIR = path.join('dist', 'apple', 'runner');
+// Packaged-runner locations from before the apple-runner/ -> apple/runner/ move. `dist` ships
+// wholesale, so a stale tree left by an older build/checkout would double-ship into the npm
+// package (and inflate the bundle-size diff, which packages the base then the PR into one dist).
+// Always remove them so only the current OUTPUT_DIR survives.
+const LEGACY_OUTPUT_DIRS = [
+  path.join('dist', 'apple-runner'),
+  path.join('dist', 'apple', 'apple-runner'),
+];
 const SKIPPED_DIR_NAMES = new Set(['.build', '.swiftpm', 'xcuserdata']);
 const SKIPPED_ROOT_FILES = new Set(['README.md', 'RUNNER_PROTOCOL.md']);
 
@@ -18,6 +26,9 @@ export function packageAppleRunnerSource(options = {}) {
   }
 
   fs.rmSync(outputRoot, { recursive: true, force: true });
+  for (const legacyDir of LEGACY_OUTPUT_DIRS) {
+    fs.rmSync(path.join(root, legacyDir), { recursive: true, force: true });
+  }
   const summary = {
     outputRoot,
     copiedFiles: 0,

scripts/write-xcuitest-cache-metadata.mjs

@@ -49,7 +49,7 @@ function resolveRunnerTestBundleId() {
 }
 
 function computeRunnerSourceFingerprint() {
-  const runnerRoot = path.join(projectRoot, 'apple-runner', 'AgentDeviceRunner');
+  const runnerRoot = path.join(projectRoot, 'apple', 'runner', 'AgentDeviceRunner');
   const files = collectRunnerSourceFiles(runnerRoot);
   const hash = crypto.createHash('sha256');
   for (const file of files) {