@dsh-workbench/shared 0.3.10 → 1.0.0-beta.0

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import type { LongTaskStep } from '../../api/long-task.js';
+import type { LongTaskStep } from '../../contract/long-task.js';
 import {
   createLongTaskHost,
   createLongTaskRegistry,

package/src/host/__tests__/market-index.test.ts

@@ -0,0 +1,179 @@
+import { describe, expect, it } from 'vitest';
+import type { MarketIndex, MarketIndexEntry } from '../../contract/protocol/market-index.js';
+import {
+  filterMarketIndex,
+  marketInstallTarget,
+  marketSourceKey,
+  parseMarketIndex,
+  parseMarketIndexJson,
+  parseSourceConfig,
+  upsertMarketEntry,
+} from '../market-index.js';
+
+function entry(change: Partial<MarketIndexEntry> = {}): MarketIndexEntry {
+  return {
+    name: '@scope/module-x',
+    versions: [
+      {
+        version: '0.1.1',
+        source: { type: 'npm', registry: 'https://npm.company.com/' },
+        publishTimestamp: 1_760_000_000,
+      },
+      { version: '0.1.0', source: { type: 'npm' } },
+    ],
+    metadata: { category: 'workbench', labels: ['workbench'], keywords: ['缺陷'] },
+    ...change,
+  };
+}
+
+function indexOf(entries: readonly MarketIndexEntry[]): unknown {
+  return { format: 1, title: { zh: '工作台模块' }, plugins: entries };
+}
+
+describe('parseMarketIndex', () => {
+  it('收下一份合法的 format 1', () => {
+    const parsed = parseMarketIndex(indexOf([entry()]));
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) return;
+    expect(parsed.index.plugins[0]?.name).toBe('@scope/module-x');
+    expect(parsed.index.title).toEqual({ zh: '工作台模块' });
+  });
+
+  it('format 不是 1 就整份拒', () => {
+    const parsed = parseMarketIndex({ format: 2, plugins: [] });
+    expect(parsed.ok).toBe(false);
+    if (parsed.ok) return;
+    expect(parsed.problems[0]?.kind).toBe('format');
+  });
+
+  it('版本没按 SemVer 降序就整份拒', () => {
+    const parsed = parseMarketIndex(indexOf([entry({ versions: [
+      { version: '0.1.0', source: { type: 'npm' } },
+      { version: '0.1.1', source: { type: 'npm' } },
+    ] })]));
+    expect(parsed.ok).toBe(false);
+    if (parsed.ok) return;
+    expect(parsed.problems[0]?.kind).toBe('version-order');
+  });
+
+  it('git source 只接受 40 位小写 commit', () => {
+    const parsed = parseMarketIndex(indexOf([entry({ versions: [
+      { version: '0.1.0', source: { type: 'git', url: 'https://git.company.com/wb/market.git', commit: 'v0.1.0' } },
+    ] })]));
+    expect(parsed.ok).toBe(false);
+    if (parsed.ok) return;
+    expect(parsed.problems[0]?.kind).toBe('git-commit');
+  });
+
+  it('同名插件整份拒', () => {
+    const parsed = parseMarketIndex(indexOf([entry(), entry()]));
+    expect(parsed.ok).toBe(false);
+    if (parsed.ok) return;
+    expect(parsed.problems[0]?.kind).toBe('duplicate-name');
+  });
+
+  it('JSON 读不懂是 not-json', () => {
+    const parsed = parseMarketIndexJson('{');
+    expect(parsed.ok).toBe(false);
+    if (parsed.ok) return;
+    expect(parsed.problems[0]?.kind).toBe('not-json');
+  });
+});
+
+describe('upsertMarketEntry', () => {
+  const base: MarketIndex = {
+    format: 1,
+    plugins: [entry({ versions: [{ version: '0.1.0', source: { type: 'npm' } }] })],
+  };
+
+  it('新版本合并进去并按 SemVer 降序', () => {
+    const next = upsertMarketEntry(base, entry({ versions: [
+      { version: '0.1.2', source: { type: 'npm' } },
+      { version: '0.1.1', source: { type: 'npm' } },
+    ] }));
+    expect(next.plugins[0]?.versions.map((one) => one.version)).toEqual(['0.1.2', '0.1.1', '0.1.0']);
+  });
+
+  it('同版本覆盖，不新增第二条', () => {
+    const next = upsertMarketEntry(base, entry({ versions: [
+      { version: '0.1.0', source: { type: 'git', url: 'https://git.company.com/wb/market.git', commit: 'a'.repeat(40) } },
+    ] }));
+    expect(next.plugins[0]?.versions).toHaveLength(1);
+    expect(next.plugins[0]?.versions[0]?.source.type).toBe('git');
+  });
+});
+
+describe('filterMarketIndex', () => {
+  const index: MarketIndex = {
+    format: 1,
+    plugins: [
+      entry(),
+      entry({ name: '@scope/module-y', metadata: { category: 'data', labels: ['cmdb'], keywords: ['服务'] } }),
+    ],
+  };
+
+  it('按 label 过滤', () => {
+    expect(filterMarketIndex(index, { label: 'cmdb' }).map((one) => one.name)).toEqual(['@scope/module-y']);
+  });
+
+  it('按分类过滤', () => {
+    expect(filterMarketIndex(index, { category: 'workbench' }).map((one) => one.name)).toEqual(['@scope/module-x']);
+  });
+
+  it('关键词搜中文描述', () => {
+    expect(filterMarketIndex(index, { query: '缺陷' }).map((one) => one.name)).toEqual(['@scope/module-x']);
+  });
+});
+
+describe('索引源与安装目标', () => {
+  it('sourceKey 忽略 localPath', () => {
+    const one = marketSourceKey({ kind: 'git', url: 'https://git.company.com/wb/market.git', ref: 'main' });
+    const other = marketSourceKey({
+      kind: 'git',
+      url: 'https://git.company.com/wb/market.git',
+      ref: 'main',
+      localPath: '/Users/x/market',
+    });
+    expect(one).toBe(other);
+  });
+
+  it('npm 目标带 registry，git 目标带 commit 与 path', () => {
+    expect(marketInstallTarget('@scope/x', '0.1.1', { type: 'npm', registry: 'https://npm.company.com/' })).toEqual({
+      spec: '@scope/x@0.1.1',
+      registry: 'https://npm.company.com/',
+    });
+    expect(
+      marketInstallTarget('@scope/x', '0.1.1', {
+        type: 'git',
+        url: 'https://git.company.com/wb/market.git',
+        commit: 'a'.repeat(40),
+        path: 'packages/module-x',
+      }),
+    ).toEqual({
+      spec: `git+https://git.company.com/wb/market.git#${'a'.repeat(40)}&path:/packages/module-x`,
+    });
+  });
+
+  it('http 源拒带凭据', () => {
+    const parsed = parseSourceConfig({
+      id: 'team',
+      label: '团队市场',
+      kind: 'http',
+      url: 'https://user:token@git.company.com/market.json',
+    });
+    expect(parsed.ok).toBe(false);
+  });
+
+  it('git 源收 scp 与 ssh 用户名形式，拒带密码', () => {
+    expect(parseSourceConfig({ id: 'team', label: '团队', kind: 'git', url: 'git@git.company.com:wb/market.git' }).ok).toBe(true);
+    expect(
+      parseSourceConfig({ id: 'team', label: '团队', kind: 'git', url: 'ssh://git@git.company.com/wb/market.git' }).ok,
+    ).toBe(true);
+    expect(
+      parseSourceConfig({ id: 'team', label: '团队', kind: 'git', url: 'https://user:token@git.company.com/wb/market.git' }).ok,
+    ).toBe(false);
+    expect(
+      parseSourceConfig({ id: 'team', label: '团队', kind: 'git', url: 'ssh://git:token@git.company.com/wb/market.git' }).ok,
+    ).toBe(false);
+  });
+});

package/src/host/__tests__/plugin-ledger.test.ts

@@ -14,7 +14,7 @@ const HOME = '/h/workbench/opencli/home';
 function entry(over: Partial<PluginLedgerEntry> = {}): PluginLedgerEntry {
   return {
     opencliHome: HOME,
-    package: 'opencli-plugin-cmdb',
+    package: 'opencli-plugin-inventory',
     installedAt: '2026-10-14T00:00:00.000Z',
     ...over,
   };
@@ -29,7 +29,7 @@ describe('台账条目的「放手」那一笔', () => {
   });
 
   it('★ 放手了的那一笔还在文件里（自动清得靠它认得"这是我们装的"），但不再是"持着"', () => {
-    const released = withReleasedEntry([entry()], HOME, 'opencli-plugin-cmdb', '2026-10-15T00:00:00.000Z');
+    const released = withReleasedEntry([entry()], HOME, 'opencli-plugin-inventory', '2026-10-15T00:00:00.000Z');
 
     expect(released).toHaveLength(1);
     expect(released[0]?.releasedAt).toBe('2026-10-15T00:00:00.000Z');
@@ -37,33 +37,33 @@ describe('台账条目的「放手」那一笔', () => {
   });
 
   it('记两次放手不覆盖第一次的时间（第二次是重放，不是新事实）', () => {
-    const once = withReleasedEntry([entry()], HOME, 'opencli-plugin-cmdb', '2026-10-15T00:00:00.000Z');
-    const twice = withReleasedEntry(once, HOME, 'opencli-plugin-cmdb', '2026-10-16T00:00:00.000Z');
+    const once = withReleasedEntry([entry()], HOME, 'opencli-plugin-inventory', '2026-10-15T00:00:00.000Z');
+    const twice = withReleasedEntry(once, HOME, 'opencli-plugin-inventory', '2026-10-16T00:00:00.000Z');
 
     expect(twice[0]?.releasedAt).toBe('2026-10-15T00:00:00.000Z');
   });
 
   it('另一个 home 的那一笔不受影响（隔离 wrapper 会换 home）', () => {
     const other = entry({ opencliHome: '/h/global/opencli/home' });
-    const released = withReleasedEntry([entry(), other], HOME, 'opencli-plugin-cmdb', '2026-10-15T00:00:00.000Z');
+    const released = withReleasedEntry([entry(), other], HOME, 'opencli-plugin-inventory', '2026-10-15T00:00:00.000Z');
 
     expect(released.find((item) => item.opencliHome !== HOME)?.releasedAt).toBeUndefined();
     expect(heldEntriesOfHome(released, other.opencliHome)).toHaveLength(1);
   });
 
   it('★ 按插件名找"用户持着的"那一份：插件名与包名两边都认（§3.4 那条映射）', () => {
-    const entries = [entry({ name: 'cmdb' })];
+    const entries = [entry({ name: 'inventory' })];
 
-    expect(heldEntryOfPlugin(entries, HOME, 'cmdb')?.package).toBe('opencli-plugin-cmdb');
-    expect(heldEntryOfPlugin(entries, HOME, 'opencli-plugin-cmdb')?.name).toBe('cmdb');
+    expect(heldEntryOfPlugin(entries, HOME, 'inventory')?.package).toBe('opencli-plugin-inventory');
+    expect(heldEntryOfPlugin(entries, HOME, 'opencli-plugin-inventory')?.name).toBe('inventory');
     expect(heldEntryOfPlugin(entries, HOME, '别的')).toBeUndefined();
     expect(heldEntryOfPlugin(entries, HOME, '  ')).toBeUndefined();
   });
 
   it('放手了的那一笔不再算"用户持着"（模块放手时就可以删它了）', () => {
-    const released = withReleasedEntry([entry({ name: 'cmdb' })], HOME, 'opencli-plugin-cmdb', '2026-10-15T00:00:00.000Z');
+    const released = withReleasedEntry([entry({ name: 'inventory' })], HOME, 'opencli-plugin-inventory', '2026-10-15T00:00:00.000Z');
 
-    expect(heldEntryOfPlugin(released, HOME, 'cmdb')).toBeUndefined();
+    expect(heldEntryOfPlugin(released, HOME, 'inventory')).toBeUndefined();
   });
 
   it('键还是「home + 包名」（同一份文件里两个 home 不互相撒谎）', () => {

package/src/host/__tests__/provision.test.ts

@@ -8,6 +8,7 @@ describe('provision 请求体：每类动作各有各的目标字段', () => {
       ['update', 'unit'],
       ['uninstall', 'unit'],
       ['install-bundle', 'spec'],
+      ['install-version', 'spec'],
       ['update-bundle', 'unit'],
       ['remove-bundle', 'name'],
       ['cancel-install', 'requestId'],
@@ -23,9 +24,9 @@ describe('provision 请求体：每类动作各有各的目标字段', () => {
       ok: true,
       request: { action: 'install', unit: 'issues' },
     });
-    expect(parseProvisionBody({ action: 'update-dependency', id: 'plugin:coding' })).toEqual({
+    expect(parseProvisionBody({ action: 'update-dependency', id: 'plugin:demo' })).toEqual({
       ok: true,
-      request: { action: 'update-dependency', id: 'plugin:coding' },
+      request: { action: 'update-dependency', id: 'plugin:demo' },
     });
   });
 
@@ -59,13 +60,13 @@ describe('provision 请求体：每类动作各有各的目标字段', () => {
   });
 
   it('用户装的那两笔插件动作按包名认目标（凭台账记的那个包名）', () => {
-    expect(parseProvisionBody({ action: 'update-plugin', name: ' opencli-plugin-cmdb ' })).toEqual({
+    expect(parseProvisionBody({ action: 'update-plugin', name: ' opencli-plugin-inventory ' })).toEqual({
       ok: true,
-      request: { action: 'update-plugin', name: 'opencli-plugin-cmdb' },
+      request: { action: 'update-plugin', name: 'opencli-plugin-inventory' },
     });
-    expect(parseProvisionBody({ action: 'uninstall-plugin', name: 'opencli-plugin-cmdb' })).toEqual({
+    expect(parseProvisionBody({ action: 'uninstall-plugin', name: 'opencli-plugin-inventory' })).toEqual({
       ok: true,
-      request: { action: 'uninstall-plugin', name: 'opencli-plugin-cmdb' },
+      request: { action: 'uninstall-plugin', name: 'opencli-plugin-inventory' },
     });
     expect(parseProvisionBody({ action: 'uninstall-plugin', unit: 'panels' })).toEqual({
       ok: false,

package/src/host/__tests__/shell-text.test.ts

@@ -1,6 +1,6 @@
 import { execFileSync } from 'node:child_process';
 import { describe, expect, it } from 'vitest';
-import { quoteShellArg, tailLines } from '../shell-text.js';
+import { quoteShellArg, quoteShellArgFor, tailLines } from '../shell-text.js';
 
 function shellSees(value: string): string {
   return execFileSync('/bin/sh', ['-c', `printf '%s' ${quoteShellArg(value)}`], {
@@ -42,3 +42,18 @@ describe('tailLines', () => {
     expect(tailLines('   ', 3)).toBe('');
   });
 });
+
+
+describe('quoteShellArgFor', () => {
+  it('win32 用双引号，路径里的空格原样保留', () => {
+    expect(quoteShellArgFor('C:\\Program Files\\dsh\\x.cjs', 'win32')).toBe('"C:\\Program Files\\dsh\\x.cjs"');
+  });
+
+  it('win32 里值自身的双引号被转义', () => {
+    expect(quoteShellArgFor('a"b', 'win32')).toBe('"a\\"b"');
+  });
+
+  it('POSIX 仍用单引号', () => {
+    expect(quoteShellArgFor("it's", 'darwin')).toBe("'it'\\''s'");
+  });
+});

package/src/host/__tests__/supply-index.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, it } from 'vitest';
+import type { ExtensionNeed, LibNeed, SupplySource } from '../../contract/needs.js';
+import { buildSupplyIndex, type SupplyDeclaration } from '../supply-index.js';
+
+function npm(pkg?: string, registryEnv = 'DSH_WB_REGISTRY'): SupplySource {
+  return {
+    kind: 'npm',
+    ...(pkg === undefined ? {} : { package: pkg }),
+    registryEnv,
+    registryDefault: 'https://registry.invalid/',
+  };
+}
+
+function extension(name: string, sources?: readonly SupplySource[]): ExtensionNeed {
+  return {
+    kind: 'extension',
+    runtime: 'opencli',
+    name,
+    commands: [`${name}-read`],
+    purpose: '测试',
+    ...(sources === undefined ? {} : { sources }),
+  };
+}
+
+function lib(name: string, sources?: readonly SupplySource[]): LibNeed {
+  return { kind: 'lib', name, purpose: '测试', ...(sources === undefined ? {} : { sources }) };
+}
+
+function manifest(id: string, needs: SupplyDeclaration['needs']): SupplyDeclaration {
+  return { id, needs };
+}
+
+describe('供给索引：一个包只有一个来源', () => {
+  it('★★ 同一个插件、同一份源：收成一个条目，两家都记上', () => {
+    const index = buildSupplyIndex([
+      manifest('a', [extension('coding', [npm('opencli-plugin-coding')])]),
+      manifest('b', [extension('coding', [npm('opencli-plugin-coding')])]),
+    ]);
+
+    expect(index.conflicts).toEqual([]);
+    expect(index.entries.size).toBe(1);
+    expect(index.entryOf('extension', 'coding')?.declarers).toEqual(['a', 'b']);
+    expect(index.sourcesOf('extension', 'coding')).toEqual([npm('opencli-plugin-coding')]);
+  });
+
+  it('★★ 一家写了源、一家没写：判冲突，不 last-wins', () => {
+    const index = buildSupplyIndex([
+      manifest('a', [extension('coding', [npm('opencli-plugin-coding')])]),
+      manifest('b', [extension('coding')]),
+    ]);
+
+    expect(index.conflicts.map((item) => item.kind)).toEqual(['source-mismatch']);
+    expect(index.entryOf('extension', 'coding')?.conflicted).toBe(true);
+    expect(index.sourcesOf('extension', 'coding')).toEqual([]);
+    expect(index.problems[0]).toContain('插件');
+  });
+
+  it('★★ 同一个插件名来自两个包：判 name-mismatch', () => {
+    const index = buildSupplyIndex([
+      manifest('a', [extension('coding', [npm('opencli-plugin-coding')])]),
+      manifest('b', [extension('coding', [{ kind: 'git', url: 'github:acme/plugin-coding' }])]),
+    ]);
+
+    expect(index.conflicts.map((item) => item.kind)).toContain('name-mismatch');
+    expect(index.entryOf('extension', 'coding')?.conflicted).toBe(true);
+  });
+
+  it('★★ 同一个包、同一个 registryEnv，一家只缺 registryDefault：不算冲突，缺的用有的一方补上', () => {
+    const index = buildSupplyIndex([
+      manifest('a', [
+        extension('coding', [{ kind: 'npm', package: 'opencli-plugin-coding', registryEnv: 'DSH_WB_REGISTRY' }]),
+      ]),
+      manifest('b', [extension('coding', [npm('opencli-plugin-coding')])]),
+    ]);
+
+    expect(index.conflicts).toEqual([]);
+    expect(index.sourcesOf('extension', 'coding')).toEqual([npm('opencli-plugin-coding')]);
+  });
+
+  it('★★ 共用库两家用不同的 registryEnv：判冲突，即使地址相同', () => {
+    const index = buildSupplyIndex([
+      manifest('argocd', [lib('opencli-workflow', [npm(undefined, 'DSH_WORKBENCH_ARGOCD_REGISTRY')])]),
+      manifest('cmdb', [lib('opencli-workflow', [npm(undefined, 'DSH_WORKBENCH_CMDB_REGISTRY')])]),
+    ]);
+
+    expect(index.conflicts).toHaveLength(1);
+    expect(index.conflicts[0]?.kind).toBe('source-mismatch');
+    expect(index.entryOf('lib', 'opencli-workflow')?.conflicted).toBe(true);
+    expect(index.sourcesOf('lib', 'opencli-workflow')).toEqual([]);
+  });
+
+  it('★★ 三家三个源：同一个包只报一条冲突，declarers 合并齐', () => {
+    const index = buildSupplyIndex([
+      manifest('a', [lib('opencli-workflow', [npm(undefined, 'DSH_WB_A_REGISTRY')])]),
+      manifest('b', [lib('opencli-workflow', [npm(undefined, 'DSH_WB_B_REGISTRY')])]),
+      manifest('c', [lib('opencli-workflow', [npm(undefined, 'DSH_WB_C_REGISTRY')])]),
+    ]);
+
+    expect(index.conflicts).toHaveLength(1);
+    expect(index.problems).toHaveLength(1);
+    expect(index.conflicts[0]?.declarers).toEqual(['a', 'b', 'c']);
+  });
+
+  it('★ 跨 kind 同名不算冲突：bin:foo / extension:foo / lib:foo 是三件事', () => {
+    const index = buildSupplyIndex([
+      manifest('a', [
+        { kind: 'bin', name: 'workflow', purpose: '测试' },
+        extension('workflow', [npm('opencli-plugin-workflow')]),
+        lib('workflow', [npm(undefined, 'DSH_WB_LIB_REGISTRY')]),
+      ]),
+    ]);
+
+    expect(index.conflicts).toEqual([]);
+    expect(index.entries.size).toBe(2);
+    expect(index.entryOf('extension', 'workflow')?.package).toBe('opencli-plugin-workflow');
+  });
+
+  it('没写 sources 的 extension 按约定落包名，进索引但不代装', () => {
+    const index = buildSupplyIndex([manifest('a', [extension('coding')])]);
+
+    expect(index.entryOf('extension', 'coding')?.package).toBe('opencli-plugin-coding');
+    expect(index.sourcesOf('extension', 'coding')).toEqual([]);
+    expect(index.conflicts).toEqual([]);
+  });
+
+  it('bin / env 不进供给索引（它们没有来源）', () => {
+    const index = buildSupplyIndex([
+      manifest('a', [
+        { kind: 'bin', name: 'gitops', purpose: '测试' },
+        { kind: 'env', name: 'DSH_TOKEN', purpose: '测试' },
+      ]),
+    ]);
+
+    expect(index.entries.size).toBe(0);
+    expect(index.conflicts).toEqual([]);
+  });
+});

package/src/host/__tests__/tokens.test.ts

@@ -0,0 +1,110 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import {
+  DSH_THEME_PACKAGE,
+  SHELL_PACKAGE,
+  nearestTokens,
+  readTokens,
+  tokenEntriesIn,
+  tokenFamilyOf,
+} from '../tokens.js';
+
+const THEME_CSS = [
+  ':root{--dsw-static-neutral-bluish-00:#fff;--dsw-font-family:system-ui;',
+  '--dsw-font-s-14:14px/22px var(--dsw-font-family);',
+  '--dsw-alias-bg-layer-1:var(--dsw-static-neutral-bluish-00)}',
+  'body[data-ds-dark-theme]{--dsw-static-neutral-bluish-00:#111;',
+  '--dsw-alias-bg-layer-1:var(--dsw-static-neutral-bluish-00)}',
+].join('');
+
+const SHELL_CSS = [
+  ':root{--wb-len-16:16px;--wb-gap-xs:6px}',
+  '.card{color:var(--dsw-alias-bg-layer-1);padding:var(--wb-len-16)}',
+].join('');
+
+function fakeTree(): string {
+  const root = mkdtempSync(join(tmpdir(), 'dsh-tokens-'));
+  writeFileSync(join(root, 'package.json'), JSON.stringify({ name: 'fixture', private: true }));
+
+  const theme = join(root, 'node_modules', ...DSH_THEME_PACKAGE.split('/'));
+  mkdirSync(join(theme, 'lib'), { recursive: true });
+  writeFileSync(join(theme, 'package.json'), JSON.stringify({ name: DSH_THEME_PACKAGE, version: '9.9.9' }));
+  writeFileSync(join(theme, 'lib', 'client.js'), `const css = ${JSON.stringify(THEME_CSS)};`);
+
+  const shell = join(root, 'node_modules', ...SHELL_PACKAGE.split('/'));
+  mkdirSync(shell, { recursive: true });
+  writeFileSync(join(shell, 'package.json'), JSON.stringify({ name: SHELL_PACKAGE, version: '1.2.3' }));
+  writeFileSync(join(shell, 'client.js'), `const css = ${JSON.stringify(SHELL_CSS)};`);
+  return root;
+}
+
+describe('tokenEntriesIn', () => {
+  it('只认前缀，浅色与深色分开取，同一个方案里只留第一处', () => {
+    const entries = tokenEntriesIn(THEME_CSS, '--dsw-');
+    expect(entries.map((one) => one.name)).toEqual([
+      '--dsw-alias-bg-layer-1',
+      '--dsw-font-family',
+      '--dsw-font-s-14',
+      '--dsw-static-neutral-bluish-00',
+    ]);
+    const layer = entries.find((one) => one.name === '--dsw-alias-bg-layer-1');
+    expect(layer?.values).toEqual({ light: '#fff', dark: '#111' });
+  });
+
+  it('值里的 var() 按同一个方案解析到底，解析不了的原样留着', () => {
+    const entries = tokenEntriesIn(`${THEME_CSS}:root{--dsw-radius-md:12px;--dsw-shadow-lv1:0 0 2px var(--dsw-missing)}`, '--dsw-');
+    const font = entries.find((one) => one.name === '--dsw-font-s-14');
+    expect(font?.values.light).toBe('14px/22px system-ui');
+    const shadow = entries.find((one) => one.name === '--dsw-shadow-lv1');
+    expect(shadow?.values.light).toBe('0 0 2px var(--dsw-missing)');
+  });
+
+  it('没有声明就给空数组，不把别的令牌带进来', () => {
+    expect(tokenEntriesIn('.x{color:red}', '--dsw-')).toEqual([]);
+    expect(tokenEntriesIn('', '--dsw-')).toEqual([]);
+  });
+});
+
+describe('readTokens', () => {
+  it('按起始目录解析出装着的主题与外壳，各带版本、文件与值', () => {
+    const root = fakeTree();
+    const set = readTokens([root]);
+    expect(set.dsw?.package).toBe(DSH_THEME_PACKAGE);
+    expect(set.dsw?.version).toBe('9.9.9');
+    expect(set.dsw?.file.endsWith(join('lib', 'client.js'))).toBe(true);
+    expect(set.wb?.version).toBe('1.2.3');
+    expect(set.wb?.entries.map((one) => one.name)).toEqual(['--wb-gap-xs', '--wb-len-16']);
+  });
+
+  it('一个都解析不到就给两个空位，不抛', () => {
+    const root = mkdtempSync(join(tmpdir(), 'dsh-tokens-empty-'));
+    expect(readTokens([root])).toEqual({ dsw: null, wb: null });
+  });
+
+  it('同一个起始目录上，前面那个包没装就接着往后找', () => {
+    const themeOnly = fakeTree();
+    const shellOnly = fakeTree();
+    const set = readTokens([themeOnly, shellOnly]);
+    expect(set.dsw?.version).toBe('9.9.9');
+    expect(set.wb?.version).toBe('1.2.3');
+  });
+});
+
+describe('nearestTokens', () => {
+  it('拼错两个字母以内给最近的几个，差太远的不要', () => {
+    const names = ['--dsw-alias-bg-layer-1', '--dsw-alias-bg-layer-2', '--dsw-alias-label-primary'];
+    expect(nearestTokens('--dsw-alias-bg-layr-1', names)).toEqual(['--dsw-alias-bg-layer-1', '--dsw-alias-bg-layer-2']);
+    expect(nearestTokens('--dsw-alias-bg-layer-9', names)).toEqual(['--dsw-alias-bg-layer-1', '--dsw-alias-bg-layer-2']);
+    expect(nearestTokens('--complete-other-thing', names)).toEqual([]);
+  });
+});
+
+describe('tokenFamilyOf', () => {
+  it('取前缀后面那一段，用来分桶', () => {
+    expect(tokenFamilyOf('--dsw-alias-bg-layer-1')).toBe('alias');
+    expect(tokenFamilyOf('--wb-len-16')).toBe('len');
+    expect(tokenFamilyOf('--dsw-radius-md')).toBe('radius');
+  });
+});

package/src/host/__tests__/version-range.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { checkVersionRange } from '../version-range.js';
+
+describe('checkVersionRange', () => {
+  it('空契约与空版本按满足算', () => {
+    expect(checkVersionRange(undefined, '1.2.3')).toBe('satisfied');
+    expect(checkVersionRange('   ', '0.0.1')).toBe('satisfied');
+  });
+
+  it('caret 收下上界以内的版本', () => {
+    expect(checkVersionRange('^0.3.0', '0.3.11')).toBe('satisfied');
+    expect(checkVersionRange('^0.3.0', '0.4.0')).toBe('unsatisfied');
+    expect(checkVersionRange('^0.1.0', '0.3.11')).toBe('unsatisfied');
+  });
+
+  it('比较符与畸形契约分得开', () => {
+    expect(checkVersionRange('>=0.3.0 <0.4.0', '0.3.11')).toBe('satisfied');
+    expect(checkVersionRange('>=0.3.0 <0.4.0', '0.4.0')).toBe('unsatisfied');
+    expect(checkVersionRange('nonsense', '0.3.11')).toBe('malformed');
+  });
+});