dsh-plugin-update 0.2.0 → 0.3.0

package/dist/host-batch.d.ts

@@ -0,0 +1,113 @@
+import { type BatchCheckOutcome, type BatchInstallOutcome, type BatchRunStep } from './batch-run.js';
+import { type UpdateConfigInput } from './config.js';
+import { type ReaderOverrides } from './host.js';
+/** 一个批量目标：要更新的那个插件包 + 它在电话表里的前缀。 */
+export interface MultiTargetSpec {
+    /** 会话内稳定键（唯一）。 */
+    key: string;
+    /** 中文名（面板行首用；缺省用 key）。 */
+    title?: string;
+    /** 目标包名（createHostUpdate 的 targetPackageName）。 */
+    packageName: string;
+    /** 该目标的单插件电话前缀（七个必须互不相同，否则串台）。 */
+    prefix: string;
+    /** 宿主侧插件标识（缺省用 batchPrefix + '-' + key）。 */
+    pluginId?: string;
+    /** 该目标的落盘使用范围（家目录）：缺省随批量范围；与批量不一致即如实拒绝（cross-scope）。 */
+    homeDir?: string;
+    /** 该目标的落盘使用范围（使用范围目录）：缺省随批量范围；与批量不一致即如实拒绝。 */
+    profileDir?: string;
+}
+/** createMultiHostUpdate 的配置。 */
+export interface MultiHostOptions {
+    /** 批量电话前缀（例 'life'）。 */
+    prefix: string;
+    /** 目标清单（顺序即会话顺序；selfKey 会被排到最后）。 */
+    targets: MultiTargetSpec[];
+    /** 「自己」的键：排序时排最后，自更新安全。 */
+    selfKey?: string | null;
+    /** 一家失败后是否停下（默认 false：继续下一家）。 */
+    stopOnFailure?: boolean;
+    /** 宿主侧 drain：定时自动推进队列（**默认关**，显式 opt-in）。 */
+    drain?: boolean;
+    /** drain 间隔（毫秒，缺省 5000，下限 1000）。 */
+    drainIntervalMs?: number;
+}
+/** 查一家：真路径打该目标的 updateCheck 电话，单测给假件。 */
+export type TargetCheckFn = (key: string, spec: MultiTargetSpec) => Promise<BatchCheckOutcome>;
+/** 装一家：requestId 是会话账本里的幂等编号（同一会话同一目标恒定）。 */
+export type TargetInstallFn = (key: string, spec: MultiTargetSpec, requestId: string, version: string) => Promise<BatchInstallOutcome>;
+/** 定时器：drain 用；测试给假件即能确定性地断言「起没起、停没停」。 */
+export interface MultiHostTimer {
+    setTimeout: (fn: () => void, ms: number) => unknown;
+    clearTimeout: (handle: unknown) => void;
+}
+/**
+ * createMultiHostUpdate 的宿主依赖（全部可选）。
+ * ctx / logCtx / desktopPnpm / pluginManager / readerOverrides 原样透传给每个目标的 createHostUpdate；
+ * 其余是本入口自己的口子（范围、传输、定时器、时钟、编号），生产可不传。
+ */
+export interface MultiHostDeps {
+    ctx?: unknown;
+    logCtx?: {
+        fire: (level: string, event: string, fields: Record<string, unknown>) => void;
+    } | null;
+    desktopPnpm?: unknown;
+    pluginManager?: unknown;
+    /** 逐目标共用的读侧覆盖（透传给每个目标）。 */
+    readerOverrides?: ReaderOverrides;
+    /** 逐目标读侧覆盖（给了就按目标算；测试与异构目标用）。 */
+    readerOverridesFor?: (spec: MultiTargetSpec) => ReaderOverrides | undefined;
+    /** 逐目标共用的配置覆盖（pluginId / prefix / targetPackageName 按目标算，不从这里来）。 */
+    config?: Omit<UpdateConfigInput, 'pluginId' | 'prefix' | 'targetPackageName'>;
+    /** 批量使用范围（会话落盘与共享队列端口用；缺省取 readerOverrides 的同名项）。 */
+    scope?: {
+        homeDir?: string;
+        profileDir?: string;
+    };
+    /** 查/装传输：缺省走单插件电话；测试给假件。 */
+    transport?: {
+        check?: TargetCheckFn;
+        install?: TargetInstallFn;
+    };
+    /** drain 的定时器（缺省真 setTimeout / clearTimeout）。 */
+    timers?: MultiHostTimer;
+    now?: () => number;
+    randomId?: () => string;
+    /** 装完之后轮询该家状态的间隔毫秒（缺省 500；后台安装收尾用）。 */
+    installPollMs?: number;
+}
+/** 批量宿主入口的返回面。 */
+export interface MultiHostUpdate {
+    /** 电话表：批量电话 + 每个目标的单插件三电话，键即电话名。 */
+    handlers: Record<string, (args?: Record<string, unknown>) => Promise<unknown>>;
+    /** 批量电话名（供接入方登记用，不写字面量）。 */
+    phoneNames: {
+        status: string;
+        check: string;
+        install: string;
+        resume: string;
+        cancel: string;
+    };
+    /** 目标清单（顺序与会话一致）。 */
+    targets: readonly MultiTargetSpec[];
+    /** 最近一次推进的读数（驱动器停下来的原因 + 步骤）：给日志与门禁用；没推过为 null。 */
+    lastRun: {
+        stoppedBecause: string;
+        steps: BatchRunStep[];
+    } | null;
+    /** 停掉 drain（接入方卸载时调）。 */
+    dispose(): void;
+}
+/**
+ * 账本幂等编号 -> 电话/队列收的编号。账本编号形如 batch:<会话>:<目标>，带冒号，
+ * 不在更新核心收的「不透明编号」形状里（[A-Za-z0-9._~-]，见 service.ts 的 validRequestId）。
+ * 纯函数：同一账本编号恒得同一电话编号，所以「同一会话同一目标恒定、重复提交不重复装」原样成立；
+ * 形状被改写过的追加短哈希，避免不同账本编号撞成同一个电话编号。
+ */
+export declare function phoneRequestIdOf(batchRequestId: string): string;
+/**
+ * 建批量宿主能力：给 N 个目标各建一份单插件宿主能力，共享一套队列端口与一份会话账本。
+ * 参数错了在装载时抛（fail fast）；使用范围冲突、装到一半、盘上没有会话这些运行期情况都走回包，不抛。
+ */
+export declare function createMultiHostUpdate(deps: (MultiHostDeps | Record<string, unknown>) | undefined, options: MultiHostOptions): MultiHostUpdate;