Skip to content

Commit bb6b98a

Browse files
committed
refactor(host): make the host explicit on contracts, host-kit and shared test-kit (#3794)
1 parent 0fb25c4 commit bb6b98a

7 files changed

Lines changed: 48 additions & 3 deletions

File tree

‎packages/contracts/src/platform-plugin.ts‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import type { DeviceInfo, Platform, PlatformSelector } from '@agent-device/kernel/device';
2+
import type { HostEnvironment } from '@agent-device/kernel/source-value';
23
import type { PlatformGatedProviderResolverKey } from './platform-providers.ts';
34
import type { Interactor, RunnerContext } from './interactor-types.ts';
45

@@ -31,8 +32,18 @@ export type PlatformPlugin = {
3132
readonly platforms: readonly Platform[];
3233
/** The multi-platform family selector, when the plugin owns more than one leaf (`apple`). */
3334
readonly familySelector?: PlatformSelector;
34-
/** Lazily builds the {@link Interactor} for `device` — wraps today's `getInteractor` switch arm. */
35-
createInteractor(device: DeviceInfo, runner: RunnerContext): Promise<Interactor>;
35+
/**
36+
* Lazily builds the {@link Interactor} for `device` — wraps today's `getInteractor` switch arm.
37+
* `host` is the environment the calling runtime captured at its entry point. Plugins are
38+
* module-level and shared by every runtime in a process, so the host arrives per call — never
39+
* bound at plugin construction — and is the same object the runtime's deps and request-bound
40+
* facets carry.
41+
*/
42+
createInteractor(
43+
device: DeviceInfo,
44+
runner: RunnerContext,
45+
host: HostEnvironment,
46+
): Promise<Interactor>;
3647
/**
3748
* The request-scope provider facet (issue #974). `platformGatedResolvers`
3849
* declares which PLATFORM-GATED request provider resolvers apply to this family's

‎packages/contracts/src/platform-runtime-host.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@ import type { DeviceInfo, Platform } from '@agent-device/kernel/device';
22
import type { JsonObject, JsonValue } from './json.ts';
33
import type { AndroidClipboardShellSupport } from './android-clipboard-support.ts';
44

5+
// The composition root names the runtime host through this contract rather than the kernel
6+
// substrate directly (R13): one host object is the whole configuration surface a runtime reads.
7+
export type { HostEnvironment } from '@agent-device/kernel/source-value';
8+
59
export type HostCommandRequest = Readonly<{
610
executable: string;
711
args: readonly string[];

‎packages/contracts/src/platform-runtime-operations.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import type { AppLogRuntimeHost, AppLogRuntimeOperations } from './app-log-runtime.ts';
22
import type { AppInventoryRuntimeOperations } from './app-inventory-runtime.ts';
3+
import type { HostEnvironment } from '@agent-device/kernel/source-value';
34
import type {
45
AndroidAppDeploymentExecutor,
56
AppDeploymentRuntimeOperations,
@@ -830,6 +831,11 @@ export const keyboardRuntimePlanUses = Object.freeze([
830831
export type PlatformRuntimeHost = AppLogRuntimeHost &
831832
NetworkRuntimeHost &
832833
Readonly<{
834+
/**
835+
* The host this runtime's entry point captured. Owners read configuration from it; it is the
836+
* same object the runtime's deps carry, never a re-capture.
837+
*/
838+
hostEnvironment: HostEnvironment;
833839
/** Focused native ports; deployment semantics remain in the owning family packages. */
834840
appleDeployment: AppleAppDeploymentExecutor;
835841
androidDeployment: AndroidAppDeploymentExecutor;

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ export {
1111
hostFileStat,
1212
hostFileStatSync,
1313
hostHomeDirectory,
14+
hostHomeDirectoryFromEnv,
1415
hostTemporaryDirectory,
1516
makeHostTemporaryDirectory,
1617
readHostBinaryFile,

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

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,16 @@ export function hostHomeDirectory(): string {
77
return os.homedir();
88
}
99

10+
/**
11+
* The home directory a named host names for itself: its own HOME (or USERPROFILE on Windows),
12+
* falling back to the process home only when the host env names none. Derive per-runtime home
13+
* config through this, never from `os.homedir()` directly, so a host whose HOME differs from the
14+
* process resolves its own paths (#3794).
15+
*/
16+
export function hostHomeDirectoryFromEnv(env: Record<string, string | undefined>): string {
17+
return env['HOME'] ?? env['USERPROFILE'] ?? hostHomeDirectory();
18+
}
19+
1020
export function hostTemporaryDirectory(): string {
1121
return os.tmpdir();
1222
}

‎packages/test-kit/src/host-environment.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,15 @@ import { withCommandHost } from '@agent-device/host-kit/command';
33
import { captureHostEnvironment } from '@agent-device/host-kit/process';
44
import type { EnvMap, HostEnvironment } from '@agent-device/kernel/source-value';
55

6+
/**
7+
* A host for tests that name one per call. Code converted to an explicit host (#3794) reads its
8+
* configuration from the object it is handed, so a suite passes this instead of binding a command
9+
* host. Its environment is the live `process.env` reference, so `vi.stubEnv` still reaches it.
10+
*/
11+
export function createLiveTestHostEnvironment(): HostEnvironment {
12+
return { env: process.env, cwd: process.cwd() };
13+
}
14+
615
/**
716
* A host for tests that boot daemon code in-process. It snapshots the process environment and
817
* working directory unless a test names its own, so a suite never shares a mutable reference to

‎packages/test-kit/src/index.ts‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,11 @@ export {
3636
dispatchDisclosureRowsOwnedBy,
3737
} from './dispatch-disclosure.fixtures.ts';
3838
export { restoreEnv } from './env.ts';
39-
export { bindTestCommandHost, createTestHostEnvironment } from './host-environment.ts';
39+
export {
40+
bindTestCommandHost,
41+
createLiveTestHostEnvironment,
42+
createTestHostEnvironment,
43+
} from './host-environment.ts';
4044
export {
4145
eagerClosureGraphOf,
4246
eagerClosureOf,

0 commit comments

Comments
 (0)