Skip to content

Commit 172f58e

Browse files
committed
refactor(platform-apple): derive the runner host port instead of mirroring host-kit
`runner/host.ts` was a hand-maintained mirror of host-kit: ~100 lines of copied type declarations, a 50-member interface re-declaring every signature, and 50 delegators, so every host-kit change was re-typed here by hand. The port now derives from the modules it fronts. `AppleRunnerHost` is a set of `Pick`s over `import type * as` namespaces -- type-only declarations R77 and the eager-closure gate see nothing of -- so a host-kit signature change reaches the runner with no edit here, and the `Pick` list is the single place that says what the runner may reach. Delegators keep their names through a `delegate(name)` helper typed by derivation, so the 28 importers are unchanged. `core/runner-host.ts` keeps naming each import rather than spreading the modules whole: spreading drops its list but puts every export of all sixteen modules on the host object (41 members to 128, +1.8 kB shipped including a vitest-only memo reset) and lets a name shared by two of them silently rebind a capability. The binding holds names only; it re-types nothing. The runner modules take the types they use straight from the owning package with `import type`. `DefinedEnvMap` was never a host capability and moves to its only caller. Host-kit gains three type exports the port needs by name -- `ExecStreamOptions`, `DiagnosticEventInput`, and `DeadlineClock`, the read side of `Deadline` that a test host substitutes a clock for -- and no behavior change. The runner-facing slice of physical-device control moves to `core/physical-device-routing.ts`, below both sides, so the port does not reach the control module, whose launch and terminate members are typed against the runner's own command executor (R9/R10 type cycle). `host.ts`: 403 -> 187 LOC. Co-Authored-By: Claude Opus 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01PPceQTJdXsEJaZsBM8ycek
1 parent f4930d6 commit 172f58e

34 files changed

Lines changed: 220 additions & 394 deletions

‎packages/host-kit/src/command.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ export {
77
execFailureDetails,
88
type ExecOptions,
99
type ExecResult,
10+
type ExecStreamOptions,
1011
isCommandTimeoutError,
1112
isExecutablePath,
1213
requireExecSuccess,

‎packages/host-kit/src/diagnostics.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
export {
22
countDiagnosticEventsByPhase,
33
createRequestId,
4+
type DiagnosticEventInput,
45
emitDiagnostic,
56
flushDiagnosticsToSessionFile,
67
getDiagnosticsMeta,

‎packages/host-kit/src/internal/diagnostics.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -123,12 +123,14 @@ export function countDiagnosticEventsByPhase(phases: readonly string[]): number
123123
return total;
124124
}
125125

126-
export function emitDiagnostic(event: {
126+
export type DiagnosticEventInput = {
127127
level?: DiagnosticLevel;
128128
phase: string;
129129
durationMs?: number;
130130
data?: Record<string, unknown>;
131-
}): void {
131+
};
132+
133+
export function emitDiagnostic(event: DiagnosticEventInput): void {
132134
const scope = diagnosticsStorage.getStore();
133135
if (!scope) return;
134136
const payload: DiagnosticEvent = {

‎packages/host-kit/src/internal/exec.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ export type ExecOptions = {
2929
maxBuffer?: number;
3030
};
3131

32-
type ExecStreamOptions = ExecOptions & {
32+
export type ExecStreamOptions = ExecOptions & {
3333
onStdoutChunk?: (chunk: string) => void;
3434
onStderrChunk?: (chunk: string) => void;
3535
onSpawn?: (child: ReturnType<typeof spawn>) => void;

‎packages/host-kit/src/internal/retry.ts‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,20 @@ type RetryPolicy = {
99
shouldRetry?: (error: unknown, attempt: number) => boolean;
1010
};
1111

12+
/**
13+
* The read side of a deadline. Holders are typed against this rather than the class so a caller
14+
* can hand one a substitute clock; {@link Deadline} is the production implementation.
15+
*/
16+
export type DeadlineClock = {
17+
remainingMs(nowMs?: number): number;
18+
elapsedMs(nowMs?: number): number;
19+
isExpired(nowMs?: number): boolean;
20+
};
21+
1222
type RetryAttemptContext = {
1323
attempt: number;
1424
maxAttempts: number;
15-
deadline?: Deadline;
25+
deadline?: DeadlineClock;
1626
};
1727

1828
type RetryTelemetryEvent = {
@@ -27,7 +37,7 @@ type RetryTelemetryEvent = {
2737
};
2838

2939
type RetryOptions = {
30-
deadline?: Deadline;
40+
deadline?: DeadlineClock;
3141
phase?: string;
3242
signal?: AbortSignal;
3343
classifyReason?: (error: unknown) => string | undefined;
@@ -51,7 +61,7 @@ const defaultOptions: Pick<RetryPolicy, 'maxAttempts' | 'baseDelayMs' | 'maxDela
5161
jitter: 0.2,
5262
};
5363

54-
export class Deadline {
64+
export class Deadline implements DeadlineClock {
5565
private readonly startedAtMs: number;
5666
private readonly expiresAtMs: number;
5767

‎packages/host-kit/src/retry.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
1-
export { Deadline, isEnvTruthy, retryWithPolicy } from './internal/retry.ts';
1+
export { Deadline, type DeadlineClock, isEnvTruthy, retryWithPolicy } from './internal/retry.ts';
22
export { sleep } from './internal/timeouts.ts';

‎packages/platform-apple/src/core/physical-device-control.ts‎

Lines changed: 5 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -27,14 +27,10 @@ import {
2727
type IosPhysicalDeviceScreenshotOptions,
2828
} from './physical-device-screenshot.ts';
2929
import { runXcrun } from './tool-provider.ts';
30-
31-
export type IosPhysicalDeviceBackend = 'coredevice' | 'xctest';
32-
/**
33-
* Only the CoreDevice tunnel address is resolved here. Which transport a runner
34-
* command uses is decided by the route resolver, which reaches this at all only
35-
* after usbmux has reported the device unattached.
36-
*/
37-
export type IosPhysicalDeviceTunnel = { tunnelIp: string | null };
30+
import type {
31+
IosPhysicalDeviceBackend,
32+
IosPhysicalDeviceRunnerControl,
33+
} from './physical-device-routing.ts';
3834

3935
type IosPhysicalDeviceLaunchOptions = {
4036
payloadUrl?: string;
@@ -43,8 +39,7 @@ type IosPhysicalDeviceLaunchOptions = {
4339
runRunnerCommand: AppleRunnerCommandExecutor;
4440
};
4541

46-
export type IosPhysicalDeviceControl = {
47-
readonly backend: IosPhysicalDeviceBackend;
42+
export type IosPhysicalDeviceControl = IosPhysicalDeviceRunnerControl & {
4843
assertAppInstallationSupported(device: DeviceInfo): void;
4944
ensureReady(device: DeviceInfo, signal?: AbortSignal): Promise<void>;
5045
listApps(device: DeviceInfo, filter: AppsFilter): Promise<IosAppInfo[]>;
@@ -75,7 +70,6 @@ export type IosPhysicalDeviceControl = {
7570
outPath: string,
7671
timeoutMs?: number,
7772
): Promise<void>;
78-
resolveTunnel(device: DeviceInfo, timeoutBudgetMs?: number): Promise<IosPhysicalDeviceTunnel>;
7973
};
8074

8175
const CONTROLS: Record<IosPhysicalDeviceBackend, IosPhysicalDeviceControl> = {
Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
import type { DeviceInfo } from '@agent-device/kernel/device';
2+
3+
/**
4+
* The physical-device routing contract, declared below both sides that need it: the runner's
5+
* command routing consults exactly this slice through its host port, and
6+
* `physical-device-control.ts` derives the full {@link IosPhysicalDeviceControl} from it. Keeping
7+
* it here leaves the runner free of the control module, whose launch and terminate members are
8+
* typed against the runner's own command executor.
9+
*/
10+
export type IosPhysicalDeviceBackend = 'coredevice' | 'xctest';
11+
12+
/**
13+
* Only the CoreDevice tunnel address is resolved here. Which transport a runner
14+
* command uses is decided by the route resolver, which reaches this at all only
15+
* after usbmux has reported the device unattached.
16+
*/
17+
export type IosPhysicalDeviceTunnel = { tunnelIp: string | null };
18+
19+
export type IosPhysicalDeviceRunnerControl = {
20+
readonly backend: IosPhysicalDeviceBackend;
21+
resolveTunnel(device: DeviceInfo, timeoutBudgetMs?: number): Promise<IosPhysicalDeviceTunnel>;
22+
};

‎packages/platform-apple/src/core/runner-host.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,12 @@ import { readApplePlistJson, runAppleToolCommand, runXcrun } from './tool-provid
5151
* production composition module (`runner-client.ts`) and by the vitest
5252
* `apple-runner` project setup, which installs the same capabilities as
5353
* overridable test defaults.
54+
*
55+
* Names only -- `AppleRunnerHost` derives every signature from the owning module, and naming each
56+
* import keeps the bundler shaking the rest of those modules away. Spreading the modules whole
57+
* instead would drop this list, at the cost of putting all of their exports on the host object at
58+
* runtime (measured: 41 members to 128, +1.8 kB shipped, including a vitest-only memo reset) and
59+
* making a name shared by two of them silently rebind a capability.
5460
*/
5561
export const appleRunnerHost: AppleRunnerHost = {
5662
runCmdStreaming,

‎packages/platform-apple/src/runner/__tests__/apple-toolchain-fixtures.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import { beforeEach, vi } from 'vitest';
22
import { appleRunnerTestHost } from '../test-host.ts';
3-
import type { ExecResult } from '../host.ts';
3+
import type { ExecResult } from '@agent-device/host-kit/command';
44

55
const STUBBED_APPLE_TOOLCHAIN = {
66
xcodeVersion: '26.2',

0 commit comments

Comments
 (0)