@syllm/brickly-test-host 0.11.0 → 0.12.0

package/index.d.ts

@@ -1,93 +1,157 @@
-/**
- * @syllm/brickly-test-host 对外类型面（手写维护，与 dist/index.cjs 对齐）。
- * 内部实现类型不外露；host 字段为不透明引用。
- */
-import type { ChildProcess } from 'node:child_process'
-
-export interface SpawnCredentials {
-  spawnId: string
-  bootstrapToken: string
-  runtimeToHostToken: string
-  hostToRuntimeToken: string
-}
-
-export interface SetFaultInput {
-  /** 完整 gRPC 方法路径，如 /brickly.runtime.v1.BrickStorageService/KvGet */
-  path: string
-  /** Brick 错误码，如 BRICK_STORAGE_NOT_FOUND */
-  brickCode: string
-  message?: string
-  /** 命中次数，默认 1 */
-  count?: number
-}
-
-export type SetFaultRequest = SetFaultInput
-
-export interface FaultRule {
-  path: string
-  brickCode: string
-  message: string
-  remaining: number
-}
-
-export interface RecordedCall {
-  path: string
-  at: number
-}
-
-export declare class HostTestControl {
-  readonly interceptor: unknown
-  setFault(input: SetFaultInput): void
-  clearFaults(): void
-  recordedCalls(): RecordedCall[]
-  /** 清空故障规则与录制（不清 storage 数据） */
-  reset(): void
-}
-
-export interface StartTestHostOptions {
-  brickId?: string
-  /** 自定义 storage 实现；默认内存版 */
-  storage?: unknown
-  /** 内存 storage 生效配额（MB），默认 50 */
-  quotaMB?: number
-}
-
-export interface TestHost {
-  /** 真宿主 gRPC 服务实例（内部类型；跨进程消费者用 spawnTestHost） */
-  readonly host: unknown
-  readonly control: HostTestControl
-  readonly endpoint: string
-  readonly spawnCredentials: SpawnCredentials
-  close(): Promise<void>
-}
-
-/** 进程内装配真宿主 + 控制面（Node 测试用）。 */
-export declare function startTestHost(options?: StartTestHostOptions): Promise<TestHost>
-
-/** 宿主进程 stdout 首行就绪 JSON（spawn 协议契约）。 */
-export interface SpawnedHostInfo {
-  /** gRPC 数据面地址，如 127.0.0.1:50051 */
-  dataEndpoint: string
-  /** 控制面 HTTP 地址，如 127.0.0.1:50052 */
-  controlEndpoint: string
-  runtimeToHostToken: string
-}
-
-export interface SpawnTestHostOptions {
-  /** 宿主 bundle 路径，默认包内 dist/host.cjs */
-  hostBundlePath?: string
-  nodeExecutable?: string
-  readyTimeoutMs?: number
-  exitTimeoutMs?: number
-}
-
-export interface SpawnedTestHost extends SpawnedHostInfo {
-  readonly process: ChildProcess
-  setFault(input: SetFaultRequest): Promise<void>
-  reset(): Promise<void>
-  recordedCalls(): Promise<RecordedCall[]>
-  close(): Promise<void>
-}
-
-/** 拉起 dist/host.cjs 子进程并提供控制面客户端。 */
-export declare function spawnTestHost(options?: SpawnTestHostOptions): Promise<SpawnedTestHost>
+/**
+ * @syllm/brickly-test-host 对外类型面（手写维护，与 dist/index.cjs 对齐）。
+ * 内部实现类型不外露；host 字段为不透明引用。
+ */
+import type { ChildProcess } from 'node:child_process'
+
+export interface SpawnCredentials {
+  spawnId: string
+  bootstrapToken: string
+  runtimeToHostToken: string
+  hostToRuntimeToken: string
+}
+
+export interface SetFaultInput {
+  /** 完整 gRPC 方法路径，如 /brickly.runtime.v1.BrickStorageService/KvGet */
+  path: string
+  /** Brick 错误码，如 BRICK_STORAGE_NOT_FOUND */
+  brickCode: string
+  message?: string
+  /** 命中次数，默认 1 */
+  count?: number
+}
+
+export type SetFaultRequest = SetFaultInput
+
+export interface FaultRule {
+  path: string
+  brickCode: string
+  message: string
+  remaining: number
+}
+
+export interface RecordedCall {
+  path: string
+  at: number
+}
+
+export declare class HostTestControl {
+  readonly interceptor: unknown
+  setFault(input: SetFaultInput): void
+  clearFaults(): void
+  recordedCalls(): RecordedCall[]
+  /** 清空故障规则与录制（不清 storage 数据） */
+  reset(): void
+}
+
+export interface StartTestHostOptions {
+  brickId?: string
+  /** 自定义 storage 实现；默认内存版 */
+  storage?: unknown
+  /** 内存 storage 生效配额（MB），默认 50 */
+  quotaMB?: number
+}
+
+export interface TestHost {
+  /** 真宿主 gRPC 服务实例（内部类型；跨进程消费者用 spawnTestHost） */
+  readonly host: unknown
+  readonly control: HostTestControl
+  readonly endpoint: string
+  readonly spawnCredentials: SpawnCredentials
+  close(): Promise<void>
+}
+
+/** 进程内装配真宿主 + 控制面（Node 测试用）。 */
+export declare function startTestHost(options?: StartTestHostOptions): Promise<TestHost>
+
+/** 宿主进程 stdout 首行就绪 JSON（spawn 协议契约）。 */
+export interface SpawnedHostInfo {
+  /** gRPC 数据面地址，如 127.0.0.1:50051 */
+  dataEndpoint: string
+  /** 控制面 HTTP 地址，如 127.0.0.1:50052 */
+  controlEndpoint: string
+  runtimeToHostToken: string
+}
+
+export interface SpawnTestHostOptions {
+  /** 宿主 bundle 路径，默认包内 dist/host.cjs */
+  hostBundlePath?: string
+  nodeExecutable?: string
+  readyTimeoutMs?: number
+  exitTimeoutMs?: number
+}
+
+export interface SpawnedTestHost extends SpawnedHostInfo {
+  readonly process: ChildProcess
+  setFault(input: SetFaultRequest): Promise<void>
+  reset(): Promise<void>
+  recordedCalls(): Promise<RecordedCall[]>
+  close(): Promise<void>
+}
+
+/** 拉起 dist/host.cjs 子进程并提供控制面客户端。 */
+export declare function spawnTestHost(options?: SpawnTestHostOptions): Promise<SpawnedTestHost>
+
+// —— 驱动面（host→runtime）：进程内消费者用 createHostDriver；
+//    外部语言走 HTTP 控制面 /spawn /invoke /interact /events/push /ui-handler ——
+
+export interface DriveSpawnInput {
+  brickId: string
+  instanceId?: string
+  origin?: 'development' | 'installed' | 'review' | 'platform'
+  version?: string
+}
+
+export interface DriveSpawnResult extends SpawnCredentials {
+  brickId: string
+  instanceId: string
+}
+
+export interface DriveInvokeInput {
+  /** 缺省用首个 spawn */
+  spawnId?: string
+  commandId: string
+  input?: unknown
+  timeoutMs?: number
+}
+
+export type DriveInteractInput = DriveInvokeInput
+
+export interface DriveError {
+  brickCode?: string
+  message: string
+  grpcStatus?: number
+}
+
+export interface DriveInvokeResult {
+  ok: boolean
+  result?: unknown
+  error?: DriveError
+}
+
+export interface DriveInteractResult {
+  ok: boolean
+  events?: unknown[]
+  result?: unknown
+  error?: DriveError
+}
+
+export interface UiCallRecord {
+  method: string
+  args: unknown[]
+  at: number
+}
+
+export declare class HostDriver {
+  spawn(input: DriveSpawnInput): DriveSpawnResult
+  runtimes(): Array<{ spawnId: string; brickId: string; instanceId: string }>
+  invoke(input: DriveInvokeInput): Promise<DriveInvokeResult>
+  interact(input: DriveInteractInput): Promise<DriveInteractResult>
+  pushEvent(input: { spawnId?: string; topic: string; payload?: unknown }): Promise<void>
+  setUiResponse(method: string, result: unknown): void
+  uiCalls(): UiCallRecord[]
+  reset(): void
+}
+
+/** 创建 host→runtime 驱动器（进程内测试用）。 */
+export declare function createHostDriver(testHost: TestHost): HostDriver

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@syllm/brickly-test-host",
-  "version": "0.11.0",
-  "description": "Brickly 真宿主测试工件：HostGrpcServer + 控制面（故障注入/请求录制），供各端 SDK 契约测试使用",
+  "version": "0.12.0",
+  "description": "Brickly 真宿主测试工件：HostGrpcServer + 控制面（故障注入/请求录制/host→runtime 驱动面），供各端 SDK 契约测试使用",
   "license": "MIT",
   "type": "commonjs",
   "main": "dist/index.cjs",