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

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');
+  });
+});

package/src/host/adapter-set.ts

@@ -0,0 +1,298 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type { DshHostContext } from '../api/dsh.js';
+import {
+  ADAPTER_SET_API_VERSION,
+  SUPPORTED_ADAPTER_API_VERSIONS,
+  type AdapterSet,
+  type CoreAdapterSet,
+} from './adapters.js';
+import { isPackageName } from './spec.js';
+
+export interface WorkbenchConfig {
+  readonly adapterSet?: string;
+}
+
+export type AdapterSetFailure =
+  | 'not-configured'
+  | 'no-profile'
+  | 'malformed'
+  | 'not-resolvable'
+  | 'import-failed'
+  | 'bad-export'
+  | 'factory-failed'
+  | 'incompatible-version'
+  | 'missing-member';
+
+export type AdapterSetLoad =
+  | { readonly ok: true; readonly spec: string; readonly set: CoreAdapterSet }
+  | {
+      readonly ok: false;
+      readonly spec?: string;
+      readonly failure: AdapterSetFailure;
+      readonly detail: string;
+      readonly cause?: unknown;
+    };
+
+const CORE_MEMBERS = ['data', 'supply', 'profile', 'probe'] as const;
+
+const CORE_METHODS = [
+  ['data', 'read'],
+  ['data', 'request'],
+  ['data', 'requestMany'],
+  ['data', 'submit'],
+  ['supply', 'resolvePluginSource'],
+  ['supply', 'libInstallCommand'],
+  ['supply', 'pluginInstallPlan'],
+  ['supply', 'latestVersion'],
+  ['supply', 'missingReleaseParts'],
+  ['supply', 'probeRelease'],
+  ['supply', 'splitNpmSpec'],
+  ['profile', 'dirOf'],
+  ['profile', 'dshPlugins'],
+  ['profile', 'selfUpdateView'],
+  ['probe', 'probeUnits'],
+  ['probe', 'registerPreflight'],
+  ['probe', 'declaredPluginCommands'],
+] as const;
+
+const FULL_MEMBERS = ['modules', 'runtime', 'plugins', 'actions'] as const;
+
+const FULL_METHODS = [
+  ['modules', 'isolatedHome'],
+  ['modules', 'cliCatalogPath'],
+  ['modules', 'vendorPluginsDir'],
+  ['modules', 'opencliInstallCommand'],
+  ['modules', 'profileDirOf'],
+  ['modules', 'profileModules'],
+  ['modules', 'readInstalledModule'],
+  ['modules', 'readProfilePackage'],
+  ['modules', 'readBundleManager'],
+  ['modules', 'createRegistryNotebook'],
+  ['modules', 'declarationGaps'],
+  ['modules', 'moduleDeclarationOf'],
+  ['modules', 'registryDeclarationOf'],
+  ['modules', 'pathDeclarationOf'],
+  ['modules', 'declarationRefusalOf'],
+  ['modules', 'refusalReason'],
+  ['modules', 'packageRouteOf'],
+  ['modules', 'isNewerVersion'],
+  ['modules', 'startSelfUpdate'],
+  ['runtime', 'packageRoot'],
+  ['runtime', 'opencliCommand'],
+  ['runtime', 'seed'],
+  ['runtime', 'warnUnwritableRoot'],
+  ['plugins', 'declarationLookup'],
+  ['plugins', 'createUnits'],
+  ['actions', 'configSyncHandler'],
+  ['actions', 'profileCreateHandler'],
+  ['actions', 'configSyncAction'],
+  ['actions', 'profileCreateAction'],
+] as const;
+
+function methodOf(value: Record<string, unknown>, member: string, method: string): unknown {
+  const part = value[member];
+  if (typeof part !== 'object' || part === null) return undefined;
+  return (part as Record<string, unknown>)[method];
+}
+
+function failure(
+  failureKind: AdapterSetFailure,
+  detail: string,
+  spec?: string,
+  cause?: unknown,
+): AdapterSetLoad {
+  return {
+    ok: false,
+    ...(spec === undefined ? {} : { spec }),
+    failure: failureKind,
+    detail,
+    ...(cause === undefined ? {} : { cause }),
+  };
+}
+
+function profileDirOf(ctx: DshHostContext): string | null {
+  const profile = ctx.get<{ dir?: unknown }>('profileContext');
+  const dir = typeof profile?.dir === 'string' ? profile.dir.trim() : '';
+  return dir === '' ? null : dir;
+}
+
+function packageDirOf(spec: string, from: string): string | undefined {
+  let dir = from;
+  for (;;) {
+    const candidate = join(dir, 'node_modules', spec);
+    if (existsSync(join(candidate, 'package.json'))) return candidate;
+    const up = dirname(dir);
+    if (up === dir) return undefined;
+    dir = up;
+  }
+}
+
+function entryOf(value: unknown): string | undefined {
+  if (typeof value === 'string') return value;
+  if (typeof value !== 'object' || value === null) return undefined;
+  const record = value as Record<string, unknown>;
+  for (const key of ['import', 'node', 'module', 'default', 'require']) {
+    const found = entryOf(record[key]);
+    if (found !== undefined) return found;
+  }
+  return undefined;
+}
+
+function exportsEntryOf(value: unknown): string | undefined {
+  if (typeof value !== 'object' || value === null) return entryOf(value);
+  const record = value as Record<string, unknown>;
+  return '.' in record ? entryOf(record['.']) : entryOf(record);
+}
+
+function esmEntryUrl(spec: string, profileDir: string): string | undefined {
+  const dir = packageDirOf(spec, profileDir);
+  if (dir === undefined) return undefined;
+  let pkg: Record<string, unknown>;
+  try {
+    pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+  const main = typeof pkg['main'] === 'string' ? pkg['main'] : undefined;
+  const module = typeof pkg['module'] === 'string' ? pkg['module'] : undefined;
+  const entry = exportsEntryOf(pkg['exports']) ?? module ?? main ?? 'index.js';
+  const file = join(dir, entry);
+  return existsSync(file) ? pathToFileURL(file).href : undefined;
+}
+
+function resolveFromProfile(spec: string, profileDir: string): string | undefined {
+  const esm = esmEntryUrl(spec, profileDir);
+  if (esm !== undefined) return esm;
+  const parent = pathToFileURL(join(profileDir, 'package.json')).href;
+  try {
+    return pathToFileURL(createRequire(parent).resolve(spec)).href;
+  } catch {
+    return undefined;
+  }
+}
+
+function versionOf(value: Record<string, unknown>): number | undefined {
+  const version = value['apiVersion'];
+  return typeof version === 'number' && Number.isInteger(version) ? version : undefined;
+}
+
+export function validateAdapterSet(value: unknown, spec: string): AdapterSetLoad {
+  if (typeof value !== 'object' || value === null) {
+    return failure('missing-member', `${spec} 的 createAdapterSet(ctx) 没回一个对象`, spec);
+  }
+  const record = value as Record<string, unknown>;
+  const version = versionOf(record);
+  if (version === undefined || !SUPPORTED_ADAPTER_API_VERSIONS.includes(version)) {
+    return failure(
+      'incompatible-version',
+      `${spec} 的适配器协议版本是 ${String(record['apiVersion'])}，工作台只认 v${ADAPTER_SET_API_VERSION}`,
+      spec,
+    );
+  }
+  const missing: string[] = CORE_MEMBERS.filter(
+    (member) => record[member] === undefined || record[member] === null,
+  );
+  for (const [member, method] of CORE_METHODS) {
+    if (typeof methodOf(record, member, method) !== 'function') missing.push(`${member}.${method}`);
+  }
+  if (typeof record['id'] !== 'string' || record['id'].trim() === '') missing.push('id');
+  if (typeof record['version'] !== 'string' || record['version'].trim() === '') missing.push('version');
+  if (FULL_MEMBERS.some((member) => record[member] !== undefined)) {
+    for (const member of FULL_MEMBERS) {
+      if (typeof record[member] !== 'object' || record[member] === null) missing.push(member);
+    }
+    for (const [member, method] of FULL_METHODS) {
+      if (typeof methodOf(record, member, method) !== 'function') missing.push(`${member}.${method}`);
+    }
+  }
+  if (missing.length > 0) {
+    return failure('missing-member', `${spec} 少了 ${missing.join(' / ')}`, spec);
+  }
+  return { ok: true, spec, set: record as unknown as CoreAdapterSet };
+}
+
+export async function loadAdapterSet(
+  ctx: DshHostContext,
+  spec: string | undefined,
+): Promise<AdapterSetLoad> {
+  const wanted = typeof spec === 'string' ? spec.trim() : spec === undefined ? '' : String(spec).trim();
+  if (wanted === '') return failure('not-configured', '没有配置 adapterSet');
+  const profileDir = profileDirOf(ctx);
+  if (profileDir === null) return failure('no-profile', '找不到 profile 目录，无法从 profile 解析适配器集合', wanted);
+  if (!isPackageName(wanted)) {
+    return failure('malformed', `适配器集合要写包名（如 @acme/adapters-set），收到 ${JSON.stringify(wanted)}`, wanted);
+  }
+
+  const url = resolveFromProfile(wanted, profileDir);
+  if (url === undefined) {
+    return failure('not-resolvable', `在 profile 里解析不到 ${wanted}，先把它装进这个 profile`, wanted);
+  }
+
+  let mod: Record<string, unknown>;
+  try {
+    mod = (await import(url)) as Record<string, unknown>;
+  } catch (error) {
+    return failure('import-failed', `${wanted} 的入口没加载成：${String(error)}`, wanted, error);
+  }
+
+  const factory = mod['createAdapterSet'] ?? mod['default'];
+  if (typeof factory !== 'function') {
+    return failure('bad-export', `${wanted} 没导出 createAdapterSet(ctx)，导出键：${Object.keys(mod).join(', ')}`, wanted);
+  }
+
+  let value: Record<string, unknown>;
+  try {
+    const raw: unknown = await factory(ctx);
+    if (typeof raw !== 'object' || raw === null) {
+      return failure('missing-member', `${wanted} 的 createAdapterSet(ctx) 没回一个对象`, wanted);
+    }
+    value = raw as Record<string, unknown>;
+  } catch (error) {
+    return failure('factory-failed', `${wanted} 的 createAdapterSet(ctx) 抛了：${String(error)}`, wanted, error);
+  }
+
+  return validateAdapterSet(value, wanted);
+}
+
+export function withDefaultAdapterSet(defaults: AdapterSet, loaded: AdapterSetLoad): AdapterSet {
+  if (!loaded.ok) return defaults;
+  const set = loaded.set as Partial<AdapterSet>;
+  return {
+    apiVersion: set.apiVersion ?? defaults.apiVersion,
+    id: set.id ?? defaults.id,
+    version: set.version ?? defaults.version,
+    data: set.data ?? defaults.data,
+    supply: set.supply ?? defaults.supply,
+    modules: set.modules ?? defaults.modules,
+    profile: set.profile ?? defaults.profile,
+    probe: set.probe ?? defaults.probe,
+    runtime: set.runtime ?? defaults.runtime,
+    plugins: set.plugins ?? defaults.plugins,
+    actions: set.actions ?? defaults.actions,
+  };
+}
+
+function isFullAdapterSet(value: CoreAdapterSet): value is AdapterSet {
+  const candidate = value as unknown as Record<string, unknown>;
+  return ['modules', 'runtime', 'plugins', 'actions'].every(
+    (member) => typeof candidate[member] === 'object' && candidate[member] !== null,
+  );
+}
+
+export async function resolveAdapterSet(
+  ctx: DshHostContext,
+  spec: string | undefined,
+  makeDefaults: () => Promise<AdapterSet>,
+): Promise<{ readonly set: AdapterSet; readonly load: AdapterSetLoad; readonly usedDefaults: boolean }> {
+  const load = await loadAdapterSet(ctx, spec);
+  if (load.ok && isFullAdapterSet(load.set)) {
+    return { set: load.set, load, usedDefaults: false };
+  }
+  const defaults = await makeDefaults();
+  return { set: withDefaultAdapterSet(defaults, load), load, usedDefaults: true };
+}
+
+export type { AdapterSet, CoreAdapterSet };