@dsh-workbench/shared 0.1.0

package/src/api/__tests__/blocker-table.test.ts

@@ -0,0 +1,253 @@
+import { describe, expect, it } from 'vitest';
+import type { Translate } from '../dsh-client';
+import type { CapabilityPayload } from '../workbench-contract';
+import { blockerOfCapability, blockerOfError } from '../blocker-table';
+
+const t: Translate = (key, params) => (params === undefined ? key : `${key}(${JSON.stringify(params)})`);
+
+describe('blockerOfError', () => {
+  it('未登录 + 有登录页地址 → 行内「去登录 ↗」+ 一颗手动「重试」（不安排自动重试）', () => {
+    const blocker = blockerOfError(
+      { code: 'auth-required', message: '未登录 CODING', helpUrl: 'https://x.coding.net/login' },
+      t,
+    );
+
+    expect(blocker.id).toBe('auth-required');
+    expect(blocker.severity).toBe('block');
+    expect(blocker.actions).toEqual([
+      {
+        kind: 'open-url',
+        label: 'blocker.login.go',
+        url: 'https://x.coding.net/login',
+        inline: true,
+      },
+      { kind: 'retry', label: 'blocker.retry' },
+    ]);
+    expect(blocker.hint).toBe('blocker.login.hint');
+  });
+
+  it('平台名由**调用方**给（同一个"未登录"能服务不同平台）', () => {
+    const coding = blockerOfError(
+      { code: 'auth-required', message: '未登录', helpUrl: 'https://x.coding.net/login' },
+      t,
+      { platform: 'Coding' },
+    );
+    const cmdb = blockerOfError(
+      { code: 'auth-required', message: '未登录', helpUrl: 'https://cmdb.example.cn/login' },
+      t,
+      { platform: 'CMDB' },
+    );
+
+    expect(coding.title).toContain('"platform":"Coding"');
+    expect(cmdb.title).toContain('"platform":"CMDB"');
+    expect(cmdb.actions[0]).toMatchObject({ kind: 'open-url', url: 'https://cmdb.example.cn/login' });
+  });
+
+  it('没给平台名 → 用不带名字的文案（不猜平台）', () => {
+    const blocker = blockerOfError({ code: 'auth-required', message: '未登录' }, t);
+
+    expect(blocker.title).toBe('blocker.login.titleGeneric');
+  });
+
+  it('未登录但没有地址 → 不给点不动的按钮，退回终端指引', () => {
+    const blocker = blockerOfError({ code: 'auth-required', message: '未登录' }, t);
+
+    expect(blocker.actions.map((action) => action.kind)).toEqual(['retry']);
+    expect(blocker.hint).toBe('blocker.login.manual');
+  });
+
+  it('权限不足 → block，主动作「打开权限页」（地址同样来自信封）', () => {
+    const blocker = blockerOfError(
+      { code: 'permission-denied', message: '没有权限', helpUrl: 'https://x.coding.net/p/x/settings' },
+      t,
+      { platform: 'Coding' },
+    );
+
+    expect(blocker.id).toBe('permission-denied');
+    expect(blocker.severity).toBe('block');
+    expect(blocker.title).toContain('"platform":"Coding"');
+    expect(blocker.actions[0]).toMatchObject({ kind: 'open-url', url: 'https://x.coding.net/p/x/settings' });
+  });
+
+  it('权限不足但没有地址 → 只给重试（不编一个页面出来）', () => {
+    const blocker = blockerOfError({ code: 'permission-denied', message: '没有权限' }, t);
+
+    expect(blocker.actions.map((action) => action.kind)).toEqual(['retry']);
+    expect(blocker.title).toBe('blocker.forbidden.titleGeneric');
+  });
+
+  it('平台专属的（"不是 X 仓库"）**不归本表管** → 走兜底，由平台层覆盖', () => {
+    const blocker = blockerOfError({ code: 'project-unsupported', message: '这个目录没有可关联的远程仓库' }, t);
+
+    expect(blocker.title).toBe('这个目录没有可关联的远程仓库');
+    expect(blocker.actions.map((action) => action.kind)).toEqual(['retry']);
+  });
+
+  it('超时 → notice + 重试（不是"坏了"）', () => {
+    const blocker = blockerOfError({ code: 'cli-timeout', message: '超时了' }, t);
+
+    expect(blocker.severity).toBe('notice');
+    expect(blocker.actions.map((action) => action.kind)).toEqual(['retry']);
+  });
+
+  it('未知错误 → 照原样说，并给重试', () => {
+    const blocker = blockerOfError({ code: 'weird', message: '怪错误' }, t);
+
+    expect(blocker.title).toBe('怪错误');
+    expect(blocker.actions.map((action) => action.kind)).toEqual(['retry']);
+  });
+
+  it('没有错误对象 → 兜底文案 + 重试（不炸）', () => {
+    expect(blockerOfError(undefined, t).title).toBe('blocker.unknown.title');
+  });
+});
+
+function capability(patch: Partial<CapabilityPayload>): CapabilityPayload {
+  return {
+    unit: 'issues',
+    status: 'ok',
+    required: [],
+    missing: [],
+    detail: '',
+    ...patch,
+  };
+}
+
+describe('blockerOfCapability', () => {
+  it('就绪 → 没有阻断', () => {
+    expect(blockerOfCapability(capability({}), t)).toBeUndefined();
+  });
+
+  it('就绪 → 没有阻断（**没有**"能凑合用但提示一下"的中间态了，见 ADR-0016）', () => {
+    expect(blockerOfCapability(capability({ status: 'ok', plugin: 'coding' }), t)).toBeUndefined();
+  });
+
+  it('★ 缺哪些命令只出现在 detail（排障区），标题里没有命令名', () => {
+    const blocker = blockerOfCapability(
+      capability({
+        status: 'missing-commands',
+        plugin: 'coding',
+        missing: ['issue-detail'],
+        detail: '1 份安装都在（缺必需：issue-detail）',
+      }),
+      t,
+    );
+
+    expect(blocker?.title).not.toContain('issue-detail');
+    expect(blocker?.detail).toContain('issue-detail');
+  });
+
+  it('降级那一档已经不存在（`ok` 就是没阻断）', () => {
+    expect(blockerOfCapability(capability({ status: 'ok', plugin: 'coding' }), t)).toBeUndefined();
+  });
+
+  it('★ 没装好 → 标题只说"这个模块还没装好"，**不点名插件**（用户不认识插件）', () => {
+    const blocker = blockerOfCapability(
+      capability({
+        status: 'missing-plugin',
+        plugin: 'coding',
+        missing: ['issues'],
+        command: 'opencli plugin install <coding 插件源>',
+      }),
+      t,
+    );
+
+    expect(blocker?.id).toBe('unit-missing-plugin');
+    expect(blocker?.title).toBe('env.unit.missingPlugin');
+    expect(blocker?.title).not.toContain('coding');
+    expect(blocker?.hint).not.toContain('插件');
+    expect(blocker?.actions.map((action) => action.kind)).toEqual(['copy', 'retry']);
+  });
+
+  it('能一键修时，主动作是「帮我升级」并带上 { action, unit }（命令由宿主侧决定）', () => {
+    const blocker = blockerOfCapability(
+      capability({ status: 'missing-commands', plugin: 'coding', missing: ['issue-detail'], fix: 'update' }),
+      t,
+    );
+
+    expect(blocker?.actions[0]).toEqual({
+      kind: 'run-fix',
+      label: 'blocker.fix.update',
+      unit: 'issues',
+      fix: 'update',
+    });
+  });
+
+  it('★ 来源解析不出（宿主给了 install 但不是 ready）→ 给「去模块市场」，不给注定失败的按钮', () => {
+    for (const install of ['env-missing', 'not-declared', 'malformed'] as const) {
+      const blocker = blockerOfCapability(
+        capability({
+          status: 'missing-plugin',
+          plugin: 'coding',
+          command: 'opencli plugin install <coding 插件源>',
+          install,
+        }),
+        t,
+      );
+
+      expect(blocker?.actions.map((action) => action.kind)).toEqual(['open-market', 'retry']);
+      expect(blocker?.actions[0]).toMatchObject({ unit: 'issues' });
+    }
+  });
+
+  it('来源解析得出时仍然给「帮我安装」+ 复制命令（open-market 不该抢戏）', () => {
+    const blocker = blockerOfCapability(
+      capability({
+        status: 'missing-plugin',
+        plugin: 'coding',
+        command: 'opencli plugin install /some/path',
+        install: 'ready',
+        fix: 'install',
+      }),
+      t,
+    );
+
+    expect(blocker?.actions.map((action) => action.kind)).toEqual(['run-fix', 'copy', 'retry']);
+  });
+
+  it('缺插件且有来源 → 主动作是「帮我安装」', () => {
+    const blocker = blockerOfCapability(
+      capability({ status: 'missing-plugin', plugin: 'coding', fix: 'install' }),
+      t,
+    );
+
+    expect(blocker?.actions[0]?.kind).toBe('run-fix');
+    expect(blocker?.actions[0]?.label).toBe('blocker.fix.install');
+    expect(blocker?.actions[0]).toMatchObject({ fix: 'install', unit: 'issues' });
+  });
+
+  it('缺命令（版本旧）→ 也给「帮我升级」', () => {
+    const blocker = blockerOfCapability(
+      capability({ status: 'missing-commands', plugin: 'coding', missing: ['issue-detail'], fix: 'update' }),
+      t,
+    );
+
+    expect(blocker?.actions[0]?.kind).toBe('run-fix');
+    expect(blocker?.actions[0]?.label).toBe('blocker.fix.update');
+  });
+
+  it('缺命令 → 列出缺哪几个，并提示多半是版本旧', () => {
+    const blocker = blockerOfCapability(
+      capability({ status: 'missing-commands', plugin: 'coding', missing: ['issue-detail'] }),
+      t,
+    );
+
+    expect(blocker?.id).toBe('unit-missing-commands');
+    expect(blocker?.title).toBe('env.unit.missingCommands');
+    expect(blocker?.title).not.toContain('issue-detail');
+    expect(blocker?.hint).toBe('env.unit.missingCommandsHint');
+  });
+
+  it('探不动 → notice，**绝不**说成缺命令/缺插件，也不给"复制安装命令"', () => {
+    const blocker = blockerOfCapability(
+      capability({ status: 'unchecked', plugin: 'coding', missing: ['issues', 'issue-detail'], detail: '拿不到执行通道' }),
+      t,
+    );
+
+    expect(blocker?.id).toBe('unit-unchecked');
+    expect(blocker?.severity).toBe('notice');
+    expect(blocker?.title).toBe('env.unit.unchecked');
+    expect(blocker?.actions.map((action) => action.kind)).toEqual(['retry']);
+    expect(blocker?.title).not.toContain('issue-detail');
+  });
+});

package/src/api/__tests__/facts.test.ts

@@ -0,0 +1,274 @@
+import { describe, expect, it, vi } from 'vitest';
+import {
+  createFactChannel,
+  factOfRoute,
+  isFactScope,
+  parseFactFrame,
+  scopePrefixOf,
+  unitFactScope,
+  type FactFrame,
+  type FactTransport,
+} from '../facts';
+
+function fakeTransport(): {
+  transport: FactTransport;
+  push(frame: Partial<FactFrame> & { readonly facts: readonly string[] }): void;
+  starts: () => number;
+  stops: () => number;
+} {
+  let onFrame: ((frame: FactFrame) => void) | null = null;
+  let starts = 0;
+  let stops = 0;
+  return {
+    starts: () => starts,
+    stops: () => stops,
+    push(frame) {
+      onFrame?.({ epoch: 'e1', rev: 1, ...frame });
+    },
+    transport: {
+      start(handlers) {
+        starts += 1;
+        onFrame = handlers.onFrame;
+        return () => {
+          stops += 1;
+          onFrame = null;
+        };
+      },
+    },
+  };
+}
+
+describe('createFactChannel', () => {
+  it('★ 建立起的第一帧只设基线，不惊动订阅者（挂载时那次取数已经包含它）', () => {
+    const wire = fakeTransport();
+    const channel = createFactChannel({ transport: wire.transport });
+    const listener = vi.fn();
+    channel.subscribe('capability', listener);
+
+    channel.applyFrame({ epoch: 'e1', rev: 7, facts: ['capability', 'panels'] });
+
+    expect(listener).not.toHaveBeenCalled();
+    expect(channel.revisionOf('capability')).toBeGreaterThan(0);
+    expect(channel.revisionOf('panels')).toBeGreaterThan(0);
+  });
+
+  it('★ 之后的帧只惊动它点名的事实（别的读者不该白跑一次）', () => {
+    const wire = fakeTransport();
+    const channel = createFactChannel({ transport: wire.transport });
+    const cmdb = vi.fn();
+    const issues = vi.fn();
+    channel.subscribe('cmdb/summary', cmdb);
+    channel.subscribe('issues', issues);
+    channel.applyFrame({ epoch: 'e1', rev: 1, facts: [] });
+
+    channel.applyFrame({ epoch: 'e1', rev: 2, facts: ['cmdb/summary'] });
+
+    expect(cmdb).toHaveBeenCalledTimes(1);
+    expect(issues).not.toHaveBeenCalled();
+    expect(channel.revisionOf('cmdb/summary')).toBe(2);
+    expect(channel.revisionOf('issues')).toBe(0);
+  });
+
+  it('★ 纪元变了（宿主热重载）→ 全部重读，哪怕修订号看着倒退了', () => {
+    const wire = fakeTransport();
+    const channel = createFactChannel({ transport: wire.transport });
+    const listener = vi.fn();
+    channel.subscribe('panels', listener);
+    channel.applyFrame({ epoch: 'e1', rev: 9, facts: [] });
+    const before = channel.revisionOf('panels');
+
+    channel.applyFrame({ epoch: 'e2', rev: 1, facts: [] });
+
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(channel.revisionOf('panels')).not.toBe(before);
+  });
+
+  it('★ refresh(fact) 与收到推送同一后果（用户按 ⟳）', () => {
+    const wire = fakeTransport();
+    const channel = createFactChannel({ transport: wire.transport });
+    const listener = vi.fn();
+    channel.subscribe('capability', listener);
+    channel.applyFrame({ epoch: 'e1', rev: 1, facts: [] });
+
+    channel.refresh('capability');
+
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(channel.revisionOf('capability')).toBeGreaterThan(1);
+  });
+
+  it('★ 最后一个订阅者走了就关传输；再订回来重新起（没人听时不占连接）', () => {
+    const wire = fakeTransport();
+    const channel = createFactChannel({ transport: wire.transport });
+    const off = channel.subscribe('panels', vi.fn());
+    const offOther = channel.subscribe('issues', vi.fn());
+
+    expect(wire.starts()).toBe(1);
+    off();
+    expect(wire.stops()).toBe(0);
+    offOther();
+    expect(wire.stops()).toBe(1);
+
+    const offAgain = channel.subscribe('panels', vi.fn());
+    expect(wire.starts()).toBe(2);
+    offAgain();
+  });
+
+  it('★ 重连后的首帧**必须惊动**（它装着断线期间的差量）—— 只有这一页的第一帧才按基线', () => {
+    const wire = fakeTransport();
+    const channel = createFactChannel({ transport: wire.transport });
+    const idle = vi.fn();
+    const first = channel.subscribe('panels', idle);
+    channel.applyFrame({ epoch: 'e1', rev: 3, facts: ['panels'] });
+    expect(idle).not.toHaveBeenCalled();
+
+    first();
+    const listener = vi.fn();
+    channel.subscribe('panels', listener);
+    channel.applyFrame({ epoch: 'e1', rev: 5, facts: ['panels'] });
+
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+
+  it('★ 点名一个命名空间 = 惊动它下面每一条已订阅的事实（装/更/卸之后，用它的模块一起重读）', () => {
+    const wire = fakeTransport();
+    const channel = createFactChannel({ transport: wire.transport });
+    const summary = vi.fn();
+    const builds = vi.fn();
+    const issues = vi.fn();
+    channel.subscribe('cmdb/summary', summary);
+    channel.subscribe('cmdb/builds?env=innettest', builds);
+    channel.subscribe('coding-issues/list', issues);
+    channel.applyFrame({ epoch: 'e1', rev: 1, facts: [] });
+
+    channel.applyFrame({ epoch: 'e1', rev: 2, facts: ['capability', 'panels', 'cmdb*'] });
+
+    expect(summary).toHaveBeenCalledTimes(1);
+    expect(builds).toHaveBeenCalledTimes(1);
+    expect(issues).not.toHaveBeenCalled();
+    expect(channel.revisionOf('cmdb/summary')).toBeGreaterThan(1);
+  });
+
+  it('命名空间不许凭空造出订阅（订阅表只由读者写），也不许越界到别的模块', () => {
+    const wire = fakeTransport();
+    const channel = createFactChannel({ transport: wire.transport });
+    const codingAnalysis = vi.fn();
+    const lookalike = vi.fn();
+    channel.subscribe('coding-analysis/summary', codingAnalysis);
+    channel.subscribe('cmdb-extra/summary', lookalike);
+    channel.applyFrame({ epoch: 'e1', rev: 1, facts: [] });
+
+    channel.applyFrame({ epoch: 'e1', rev: 2, facts: ['cmdb*'] });
+
+    expect(codingAnalysis).not.toHaveBeenCalled();
+    expect(lookalike).not.toHaveBeenCalled();
+    expect(channel.revisionOf('cmdb/never-subscribed')).toBe(0);
+    expect(channel.subscriberCount()).toBe(2);
+  });
+
+  it('★ 命名空间也走"第一帧只设基线"这条规则（重开页面不为历史那次动作白读一遍）', () => {
+    const wire = fakeTransport();
+    const channel = createFactChannel({ transport: wire.transport });
+    const listener = vi.fn();
+    channel.subscribe('cmdb/builds?env=innettest', listener);
+
+    channel.applyFrame({ epoch: 'e1', rev: 4, facts: ['cmdb*'] });
+
+    expect(listener).not.toHaveBeenCalled();
+    expect(channel.revisionOf('cmdb/builds?env=innettest')).toBeGreaterThan(0);
+  });
+
+  it('refresh(命名空间) 只惊动它下面的事实（本地失效也按模块点名，不是一律全量）', () => {
+    const wire = fakeTransport();
+    const channel = createFactChannel({ transport: wire.transport });
+    const cmdb = vi.fn();
+    const issues = vi.fn();
+    channel.subscribe('cmdb/summary', cmdb);
+    channel.subscribe('coding-issues/list', issues);
+    channel.applyFrame({ epoch: 'e1', rev: 1, facts: [] });
+
+    channel.refresh('cmdb*');
+
+    expect(cmdb).toHaveBeenCalledTimes(1);
+    expect(issues).not.toHaveBeenCalled();
+  });
+
+  it('传输把当前修订交回去（重连只要增量）', () => {
+    const seen: number[] = [];
+    const channel = createFactChannel({
+      transport: {
+        start(handlers) {
+          seen.push(handlers.cursor());
+          return () => {};
+        },
+      },
+    });
+    channel.applyFrame({ epoch: 'e1', rev: 4, facts: ['panels'] });
+    channel.subscribe('panels', vi.fn());
+
+    expect(seen).toEqual([4]);
+  });
+});
+
+describe('parseFactFrame', () => {
+  it('★ 推送帧没有纪元也认（宿主只在首帧带它）—— 认不出就是"拨了开关不亮"', () => {
+    expect(parseFactFrame('{"type":"bump","rev":12,"facts":["panels","capability"]}')).toEqual({
+      rev: 12,
+      facts: ['panels', 'capability'],
+    });
+  });
+
+  it('★ 缺纪元的帧照样惊动它点名的事实（推送这条路不能整条哑掉）', () => {
+    const wire = fakeTransport();
+    const channel = createFactChannel({ transport: wire.transport });
+    const listener = vi.fn();
+    channel.subscribe('panels', listener);
+    channel.applyFrame({ epoch: 'e1', rev: 10, facts: ['panels'] });
+    listener.mockClear();
+
+    channel.applyFrame({ rev: 11, facts: ['panels'] });
+
+    expect(listener).toHaveBeenCalledTimes(1);
+    expect(channel.revisionOf('panels')).toBeGreaterThan(0);
+  });
+
+  it('缺纪元 ≠ 换纪元（推送帧不该把"宿主重载过"误报成全量重读）', () => {
+    const wire = fakeTransport();
+    const channel = createFactChannel({ transport: wire.transport });
+    const listener = vi.fn();
+    channel.applyFrame({ epoch: 'e1', rev: 3, facts: [] });
+    channel.subscribe('panels', listener);
+
+    channel.applyFrame({ rev: 4, facts: [] });
+    channel.applyFrame({ epoch: 'e1', rev: 5, facts: [] });
+    expect(listener).not.toHaveBeenCalled();
+
+    channel.applyFrame({ epoch: 'e2', rev: 1, facts: [] });
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+
+  it('读不懂的帧丢掉（不猜）：非字符串 / 坏 JSON / 没有修订号', () => {
+    expect(parseFactFrame(undefined)).toBeNull();
+    expect(parseFactFrame({ rev: 1, facts: [] })).toBeNull();
+    expect(parseFactFrame('{ 这不是 JSON')).toBeNull();
+    expect(parseFactFrame('{"type":"bump","facts":["panels"]}')).toBeNull();
+    expect(parseFactFrame('{"rev":2}')).toEqual({ rev: 2, facts: [] });
+    expect(parseFactFrame('{"rev":2,"facts":["panels",7]}')).toEqual({ rev: 2, facts: ['panels'] });
+  });
+});
+
+describe('factOfRoute', () => {
+  it('事实名就是路由名（不另起一套词汇，读与订阅不可能各说各话）', () => {
+    expect(factOfRoute('cmdb/summary')).toBe('cmdb/summary');
+    expect(factOfRoute('capability')).toBe('capability');
+  });
+});
+
+describe('unitFactScope', () => {
+  it('命名空间 = 模块 id + `*`（"这个模块的数据全作废"只写一个字符串）', () => {
+    expect(unitFactScope('cmdb')).toBe('cmdb*');
+    expect(isFactScope('cmdb*')).toBe(true);
+    expect(isFactScope('*')).toBe(false);
+    expect(isFactScope('cmdb/summary')).toBe(false);
+    expect(scopePrefixOf('cmdb*')).toBe('cmdb');
+  });
+});

package/src/api/__tests__/host-write.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+import { writeOutcomeOf, writeRoute } from '../host-write';
+
+describe('writeRoute', () => {
+  it('三条通道各自拼得出路由（面板上的写只有这三条）', () => {
+    expect(writeRoute('prefs', 'cmdb')).toBe('prefs/cmdb');
+    expect(writeRoute('actions', 'cmdb-release')).toBe('actions/cmdb-release');
+    expect(writeRoute('provision', '')).toBe('provision');
+  });
+
+  it('provision 忽略资源名（它只发 {action, unit}，没有资源段）', () => {
+    expect(writeRoute('provision', 'issues')).toBe('provision');
+  });
+});
+
+describe('writeOutcomeOf', () => {
+  it('成了 → 值原样交出', () => {
+    const outcome = writeOutcomeOf<{ text: string }>({ ok: true, text: '发出去了' }, '网络不通');
+
+    expect(outcome).toEqual({ ok: true, value: { ok: true, text: '发出去了' } });
+  });
+
+  it('★ 请求没到（null）→ 用调用方给的那句网络文案', () => {
+    expect(writeOutcomeOf(null, '网络不通')).toEqual({ ok: false, message: '网络不通' });
+  });
+
+  it('★ 宿主说失败 → 原样用宿主的话 + detail（不再包一层"操作失败"）', () => {
+    const outcome = writeOutcomeOf(
+      { ok: false, error: { code: 'cmdb/release-blocked', message: '生产环境要先审批', detail: 'job 1234' } },
+      '网络不通',
+    );
+
+    expect(outcome).toEqual({ ok: false, message: '生产环境要先审批', detail: 'job 1234' });
+  });
+
+  it('没有 detail 就不给那个字段（别塞一个 undefined 进类型里）', () => {
+    const outcome = writeOutcomeOf({ ok: false, error: { code: 'x', message: '不行' } }, '网络不通');
+
+    expect(outcome).toEqual({ ok: false, message: '不行' });
+    expect(Object.keys(outcome)).not.toContain('detail');
+  });
+
+  it('★ 领域结果那一档（`{ok:false, text}`，没有 `error`）→ 用生产者自己那句话，**不抛异常**', () => {
+    const outcome = writeOutcomeOf(
+      { ok: false, text: 'innettest 没有发布配置（configs 查不到）' } as never,
+      '网络不通',
+    );
+
+    expect(outcome).toEqual({ ok: false, message: 'innettest 没有发布配置（configs 查不到）' });
+  });
+
+  it('★ 连话都没说（`{ok:false}`）→ 用调用方的兜底文案，还是不抛', () => {
+    expect(writeOutcomeOf({ ok: false } as never, '网络不通')).toEqual({ ok: false, message: '网络不通' });
+  });
+});

package/src/api/__tests__/long-task.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+import { longTaskDot, longTaskPollMs, longTaskRunsOf, runsRouteOf } from '../long-task';
+
+describe('runsRouteOf', () => {
+  it('★ 事实名 = 路由名（三处同一个来源，改一处不可能漏另一处）', () => {
+    expect(runsRouteOf('cmdb')).toBe('cmdb/runs');
+    expect(runsRouteOf('issues')).toBe('issues/runs');
+  });
+});
+
+describe('longTaskDot', () => {
+  it('★ 两个"还在等"的状态都转圈：等编排与等你登录是同一个信号', () => {
+    expect(longTaskDot('running')).toBe('ongoing');
+    expect(longTaskDot('needs-login')).toBe('ongoing');
+    expect(longTaskDot('ok')).toBe('done');
+    expect(longTaskDot('failed')).toBe('error');
+  });
+});
+
+describe('longTaskRunsOf（这一读交回的"当前那些趟"）', () => {
+  const runs = [{ id: 'run-1', target: 'test', status: 'running' }];
+
+  it('读到了 → 原样交出（套件自己投影的形状，外壳不裁剪）', () => {
+    expect(longTaskRunsOf({ phase: 'ready', value: { runs } })).toEqual(runs);
+  });
+
+  it('★ 重取期间（`phase` 转 loading、但 `value` 还留着）→ **仍然交出那一份**', () => {
+    expect(longTaskRunsOf({ phase: 'loading', value: { runs } })).toEqual(runs);
+    expect(longTaskRunsOf({ phase: 'error', value: { runs } })).toEqual(runs);
+  });
+
+  it('还没读到过 / 读回来是空的 → 空数组（界面据此不画那一行）', () => {
+    expect(longTaskRunsOf({})).toEqual([]);
+    expect(longTaskRunsOf({ value: { runs: [] } })).toEqual([]);
+  });
+});
+
+describe('longTaskPollMs（轮询两档：还在跑要快，都收尾了也要问）', () => {
+  it('还在跑 → 快档（进度要跟手）', () => {
+    expect(longTaskPollMs(true)).toBe(1500);
+  });
+
+  it('★ 都收尾了 → **慢档但不停**（停了之后"别人起了一趟"就只剩推送那一条路）', () => {
+    expect(longTaskPollMs(false)).toBe(10_000);
+    expect(longTaskPollMs(false)).toBeLessThan(Number.POSITIVE_INFINITY);
+  });
+
+  it('调用方钉了值就用它（测试 / 特殊界面）', () => {
+    expect(longTaskPollMs(true, 50)).toBe(50);
+    expect(longTaskPollMs(false, 50)).toBe(50);
+  });
+});