Skip to content

Commit 576fe15

Browse files
committed
refactor(apple): extract the runner client into @agent-device/apple-runner (#2040)
Moves src/platforms/apple/core/runner/ (34 modules + apple-runner-platform.ts and the 30 runner test suites) into a dedicated private workspace package. Host capabilities (exec, diagnostics, retry, process probes, locks, Apple tooling, physical-device control, progress/cancel, boot classification) enter through the package-owned AppleRunnerHost port; the root composition module src/platforms/apple/core/runner-client.ts constructs the client exactly once and re-exposes the bound operations under their historical names. Types and host-free helpers come from the package façade; the factory lives behind ./client so the façade stays implementation-lazy; package tests receive the real root capabilities through the ./test-host seam installed by the apple-runner vitest project.
1 parent 8748634 commit 576fe15

177 files changed

Lines changed: 2110 additions & 1064 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/actions/setup-apple-runner-build/action.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ runs:
4444
id: source-hash
4545
run: |
4646
set -euo pipefail
47-
echo "value=${{ hashFiles('apple/runner/**', 'scripts/build-xcuitest-apple.sh', 'scripts/patch-xcuitest-runner-icon.ts', 'scripts/write-xcuitest-cache-metadata.mjs', 'src/platforms/apple/core/apple-runner-platform.ts', 'src/platforms/apple/core/runner/runner-cache-metadata.ts', 'src/platforms/apple/core/runner/runner-icon.ts', 'src/platforms/apple/core/runner/runner-xctestrun.ts', 'src/platforms/apple/core/runner/runner-xctestrun-products.ts', '.github/actions/setup-apple-runner-build/action.yml', 'package.json', 'pnpm-lock.yaml') }}" >> "$GITHUB_OUTPUT"
47+
echo "value=${{ hashFiles('apple/runner/**', 'scripts/build-xcuitest-apple.sh', 'scripts/patch-xcuitest-runner-icon.ts', 'scripts/write-xcuitest-cache-metadata.mjs', 'packages/apple-runner/src/apple-runner-platform.ts', 'packages/apple-runner/src/runner-cache-metadata.ts', 'packages/apple-runner/src/runner-icon.ts', 'packages/apple-runner/src/runner-xctestrun.ts', 'packages/apple-runner/src/runner-xctestrun-products.ts', '.github/actions/setup-apple-runner-build/action.yml', 'package.json', 'pnpm-lock.yaml') }}" >> "$GITHUB_OUTPUT"
4848
shell: bash
4949

5050
- name: Resolve Apple runner build variant

‎.github/workflows/xctest-nightly.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -123,7 +123,7 @@ jobs:
123123
# `RunnerTests/testCommand` is not a test. It is the runner's server entry point: it
124124
# opens an NWListener and blocks in `XCTWaiter.wait(timeout: 24 * 60 * 60)` until a
125125
# client closes the session, which is exactly how production drives it
126-
# (src/platforms/apple/core/runner/runner-session.ts always passes it as the sole
126+
# (packages/apple-runner/src/runner-session.ts always passes it as the sole
127127
# `-only-testing:`). It compiles unconditionally — the `#if AGENT_DEVICE_RUNNER_UNIT_TESTS`
128128
# block ends well above it — so an unfiltered run reaches it in alphabetical order and
129129
# hangs the job until `timeout-minutes`. Its one escape hatch,

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,7 @@ cross-language rules change through golden tables under `contracts/fixtures/`.
112112

113113
## Runtime and diagnostics seams
114114

115-
The OS-neutral Apple runner lives under `src/platforms/apple/core/runner/`. For connection errors,
115+
The OS-neutral Apple runner lives under `packages/apple-runner/src/`. For connection errors,
116116
retry policy, or command typing, start at `runner-contract.ts`; transport stays below session/client
117117
behavior, and xctestrun build/cache logic stays outside request execution.
118118

‎apple/runner/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Current internal runner for iOS, tvOS, and macOS desktop automation.
1515
Protocol and maintenance references:
1616

1717
- Protocol overview: [`RUNNER_PROTOCOL.md`](RUNNER_PROTOCOL.md)
18-
- TypeScript client: [`../../src/platforms/apple/core/runner/runner-client.ts`](../../src/platforms/apple/core/runner/runner-client.ts)
18+
- TypeScript client: [`../../packages/apple-runner/src/runner-client.ts`](../../packages/apple-runner/src/runner-client.ts)
1919
- Swift wire models: [`AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift)
2020

2121
## UITest Runner File Map

‎apple/runner/RUNNER_PROTOCOL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ than silently applied:
6464

6565
The current command names are defined in:
6666

67-
- [`../../src/platforms/apple/core/runner/runner-client.ts`](../../src/platforms/apple/core/runner/runner-client.ts)
67+
- [`../../packages/apple-runner/src/runner-client.ts`](../../packages/apple-runner/src/runner-client.ts)
6868
- [`AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift)
6969

7070
## Response Shape

‎docs/adr/0019-request-bound-platform-runtime.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -129,6 +129,17 @@ platform-common package, and it preserves the package façades' implementation-l
129129
Its introduction carries the normal workspace-package compliance surface: `check:affected`
130130
selection, R11/R13 package enumeration, and the composite typecheck project list.
131131

132+
The Apple XCUITest runner client lives in the private `@agent-device/apple-runner` domain package
133+
in the same stratum (`kernel < contracts/xml < apple-runner < platform/provider/daemon`), not in
134+
`packages/platform-apple`: its consumers include daemon and root Apple platform code that R13 bars
135+
from importing a concrete platform package, and its mechanics own their cache files and usbmux
136+
sockets directly. Host authority still enters through one focused injected port (`AppleRunnerHost`
137+
— process execution, diagnostics, retry, probes, locks, foreground Apple tooling, physical-device
138+
control), constructed by exactly one composition root. The dedicated `apple-runner-policy` layering
139+
rule pins what R13's `platform-*` glob cannot see: no raw process primitives in the package's
140+
production sources, one importer for the host-bound `./client` factory subpath, and one installer
141+
for the `./test-host` seam.
142+
132143
Canonical family, `AppleOS`, public-leaf, and selector identity remain declared in
133144
`@agent-device/kernel/device`. Platform-module metadata references one canonical family; during
134145
coexistence the legacy plugin registry derives its family identity from the same declaration rather

‎fallow-baselines/health.json‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -374,11 +374,6 @@
374374
"count": 1
375375
}
376376
},
377-
"src/platforms/apple/core/runner/runner-startup-transport.ts": {
378-
"crap_high": {
379-
"count": 1
380-
}
381-
},
382377
"src/platforms/apple/core/screenshot-status-bar.ts": {
383378
"complexity_moderate": {
384379
"count": 1
@@ -557,6 +552,11 @@
557552
"crap_moderate": {
558553
"count": 1
559554
}
555+
},
556+
"packages/apple-runner/src/runner-startup-transport.ts": {
557+
"crap_high": {
558+
"count": 1
559+
}
560560
}
561561
},
562562
"runtime_coverage_findings": [],

‎package.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -161,7 +161,7 @@
161161
"check:unit": "pnpm test:unit && pnpm check:tmpdir-leaks && pnpm test:smoke",
162162
"check": "pnpm check:tooling && pnpm check:fallow && pnpm check:unit",
163163
"prepack": "pnpm check:mcp-metadata && pnpm package:npm",
164-
"typecheck": "tsc -b packages/xml packages/kernel packages/contracts packages/capture-kit packages/platform-apple packages/platform-android packages/platform-harmonyos packages/platform-vega packages/platform-linux packages/platform-web packages/ad-script packages/selectors packages/ad-replay packages/maestro packages/replay-test packages/provider-webdriver packages/provider-limrun && tsc -p tsconfig.json && tsc -p examples/sdk/tsconfig.json",
164+
"typecheck": "tsc -b packages/xml packages/kernel packages/contracts packages/apple-runner packages/capture-kit packages/platform-apple packages/platform-android packages/platform-harmonyos packages/platform-vega packages/platform-linux packages/platform-web packages/ad-script packages/selectors packages/ad-replay packages/maestro packages/replay-test packages/provider-webdriver packages/provider-limrun && tsc -p tsconfig.json && tsc -p examples/sdk/tsconfig.json",
165165
"test-app:install": "pnpm install --dir examples/test-app",
166166
"test-app:start": "pnpm --dir examples/test-app start",
167167
"test-app:ios": "pnpm --dir examples/test-app ios",
@@ -276,6 +276,7 @@
276276
"devDependencies": {
277277
"@agent-device/ad-replay": "workspace:*",
278278
"@agent-device/ad-script": "workspace:*",
279+
"@agent-device/apple-runner": "workspace:*",
279280
"@agent-device/capture-kit": "workspace:*",
280281
"@agent-device/contracts": "workspace:*",
281282
"@agent-device/kernel": "workspace:*",

‎packages/apple-runner/package.json‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
{
2+
"name": "@agent-device/apple-runner",
3+
"version": "0.0.0",
4+
"private": true,
5+
"type": "module",
6+
"description": "Apple XCUITest runner client for agent-device: artifact cache, build/prewarm, request transport, and session lifecycle. Host process/tool capabilities enter through the injected AppleRunnerHost port.",
7+
"dependencies": {
8+
"@agent-device/contracts": "workspace:*",
9+
"@agent-device/kernel": "workspace:*",
10+
"@agent-device/xml": "workspace:*"
11+
},
12+
"exports": {
13+
".": {
14+
"types": "./src/index.ts",
15+
"default": "./src/index.ts"
16+
},
17+
"./client": {
18+
"types": "./src/client.ts",
19+
"default": "./src/client.ts"
20+
},
21+
"./test-host": {
22+
"types": "./src/test-host.ts",
23+
"default": "./src/test-host.ts"
24+
}
25+
}
26+
}

src/platforms/apple/core/__tests__/apple-runner-platform.test.ts renamed to packages/apple-runner/src/__tests__/apple-runner-platform.test.ts

File renamed without changes.

0 commit comments

Comments
 (0)