@dsh-workbench/shared 0.1.16 → 0.1.18

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

@@ -0,0 +1,94 @@
+import { describe, expect, it } from 'vitest';
+import {
+  heldEntriesOfHome,
+  heldEntryOfPlugin,
+  ledgerKeyOf,
+  parsePluginLedger,
+  pluginRetentionOf,
+  withReleasedEntry,
+  type PluginLedgerEntry,
+} from '../plugin-ledger.js';
+
+const HOME = '/h/workbench/opencli/home';
+
+function entry(over: Partial<PluginLedgerEntry> = {}): PluginLedgerEntry {
+  return {
+    opencliHome: HOME,
+    package: 'opencli-plugin-cmdb',
+    installedAt: '2026-10-14T00:00:00.000Z',
+    ...over,
+  };
+}
+
+describe('台账条目的「放手」那一笔', () => {
+  it('老文件（没有 releasedAt）读出来还是"用户持着"（读旧数据，不是垫片）', () => {
+    const parsed = parsePluginLedger({ entries: [entry()] });
+    expect(parsed).toHaveLength(1);
+    expect(parsed[0]?.releasedAt).toBeUndefined();
+    expect(heldEntriesOfHome(parsed, HOME)).toHaveLength(1);
+  });
+
+  it('★ 放手了的那一笔还在文件里（自动清得靠它认得"这是我们装的"），但不再是"持着"', () => {
+    const released = withReleasedEntry([entry()], HOME, 'opencli-plugin-cmdb', '2026-10-15T00:00:00.000Z');
+
+    expect(released).toHaveLength(1);
+    expect(released[0]?.releasedAt).toBe('2026-10-15T00:00:00.000Z');
+    expect(heldEntriesOfHome(released, HOME)).toEqual([]);
+  });
+
+  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');
+
+    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');
+
+    expect(released.find((item) => item.opencliHome !== HOME)?.releasedAt).toBeUndefined();
+    expect(heldEntriesOfHome(released, other.opencliHome)).toHaveLength(1);
+  });
+
+  it('★ 按插件名找"用户持着的"那一份：插件名与包名两边都认（§3.4 那条映射）', () => {
+    const entries = [entry({ name: 'cmdb' })];
+
+    expect(heldEntryOfPlugin(entries, HOME, 'cmdb')?.package).toBe('opencli-plugin-cmdb');
+    expect(heldEntryOfPlugin(entries, HOME, 'opencli-plugin-cmdb')?.name).toBe('cmdb');
+    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');
+
+    expect(heldEntryOfPlugin(released, HOME, 'cmdb')).toBeUndefined();
+  });
+
+  it('键还是「home + 包名」（同一份文件里两个 home 不互相撒谎）', () => {
+    expect(ledgerKeyOf({ opencliHome: '/a', package: 'x' })).not.toBe(
+      ledgerKeyOf({ opencliHome: '/b', package: 'x' }),
+    );
+  });
+});
+
+describe('物理去留：由谁主张说话（动作与结果分层那条）', () => {
+  it('用户还持着 → 留着（模块放手不动它）', () => {
+    expect(pluginRetentionOf({ held: true, claimedBy: [], trustworthy: true })).toBe('keep-held');
+    expect(pluginRetentionOf({ held: true, claimedBy: ['x'], trustworthy: false })).toBe('keep-held');
+  });
+
+  it('★ 不是用户持的、引用又不可信 → 一律不删（宁可留一个孤儿，也不删别人的文件）', () => {
+    expect(pluginRetentionOf({ held: false, claimedBy: [], trustworthy: false })).toBe('keep-unsure');
+    expect(pluginRetentionOf({ held: false, claimedBy: ['x'], trustworthy: false })).toBe('keep-unsure');
+  });
+
+  it('还有模块在用 → 留着（点了卸载，文件也不动）', () => {
+    expect(pluginRetentionOf({ held: false, claimedBy: ['issues'], trustworthy: true })).toBe('keep-claimed');
+  });
+
+  it('★ 引用可信 + 没人主张 → 这才是唯一敢删的那一格', () => {
+    expect(pluginRetentionOf({ held: false, claimedBy: [], trustworthy: true })).toBe('remove');
+  });
+});

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

@@ -12,6 +12,8 @@ describe('provision 请求体：每类动作各有各的目标字段', () => {
       ['remove-bundle', 'name'],
       ['cancel-install', 'requestId'],
       ['update-dependency', 'id'],
+      ['update-plugin', 'name'],
+      ['uninstall-plugin', 'name'],
     ]);
   });
 
@@ -55,6 +57,22 @@ describe('provision 请求体：每类动作各有各的目标字段', () => {
     });
   });
 
+  it('用户装的那两笔插件动作按包名认目标（凭台账记的那个包名）', () => {
+    expect(parseProvisionBody({ action: 'update-plugin', name: ' opencli-plugin-cmdb ' })).toEqual({
+      ok: true,
+      request: { action: 'update-plugin', name: 'opencli-plugin-cmdb' },
+    });
+    expect(parseProvisionBody({ action: 'uninstall-plugin', name: 'opencli-plugin-cmdb' })).toEqual({
+      ok: true,
+      request: { action: 'uninstall-plugin', name: 'opencli-plugin-cmdb' },
+    });
+    expect(parseProvisionBody({ action: 'uninstall-plugin', unit: 'panels' })).toEqual({
+      ok: false,
+      code: 'workbench/no-name',
+      message: '缺少 name',
+    });
+  });
+
   it('拿错字段不算数（spec 动作给了 unit 也要打回）', () => {
     expect(parseProvisionBody({ action: 'install-bundle', unit: 'issues' })).toEqual({
       ok: false,

package/src/host/plugin-ledger.ts

@@ -0,0 +1,152 @@
+import type { ModuleStore } from './workspace-store.js';
+
+export const PLUGIN_LEDGER_FILE = 'plugins.json';
+
+export interface PluginLedgerEntry {
+  readonly opencliHome: string;
+  readonly package: string;
+  readonly name?: string;
+  readonly registry?: string;
+  readonly local?: boolean;
+  readonly installedAt: string;
+  readonly releasedAt?: string;
+}
+
+export function ledgerKeyOf(entry: {
+  readonly opencliHome: string;
+  readonly package: string;
+}): string {
+  return `${entry.opencliHome}\u0000${entry.package}`;
+}
+
+function textOf(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  const trimmed = value.trim();
+  return trimmed === '' ? undefined : trimmed;
+}
+
+function entryOf(value: unknown): PluginLedgerEntry | undefined {
+  if (typeof value !== 'object' || value === null) return undefined;
+  const box = value as Readonly<Record<string, unknown>>;
+  const opencliHome = textOf(box['opencliHome']);
+  const pkg = textOf(box['package']);
+  const installedAt = textOf(box['installedAt']);
+  if (opencliHome === undefined || pkg === undefined || installedAt === undefined) return undefined;
+  const name = textOf(box['name']);
+  const registry = textOf(box['registry']);
+  const releasedAt = textOf(box['releasedAt']);
+  return {
+    opencliHome,
+    package: pkg,
+    installedAt,
+    ...(name === undefined ? {} : { name }),
+    ...(registry === undefined ? {} : { registry }),
+    ...(releasedAt === undefined ? {} : { releasedAt }),
+    ...(box['local'] === true ? { local: true } : {}),
+  };
+}
+
+export function parsePluginLedger(raw: unknown): PluginLedgerEntry[] {
+  if (typeof raw !== 'object' || raw === null) return [];
+  const list = (raw as Readonly<Record<string, unknown>>)['entries'];
+  if (!Array.isArray(list)) return [];
+  const entries: PluginLedgerEntry[] = [];
+  for (const item of list) {
+    const entry = entryOf(item);
+    if (entry === undefined) continue;
+    if (entries.some((known) => ledgerKeyOf(known) === ledgerKeyOf(entry))) continue;
+    entries.push(entry);
+  }
+  return entries;
+}
+
+export function readPluginLedger(store: ModuleStore): PluginLedgerEntry[] {
+  return parsePluginLedger(store.read(PLUGIN_LEDGER_FILE));
+}
+
+export function writePluginLedger(store: ModuleStore, entries: readonly PluginLedgerEntry[]): void {
+  if (entries.length === 0) {
+    store.remove(PLUGIN_LEDGER_FILE);
+    return;
+  }
+  store.write(PLUGIN_LEDGER_FILE, { entries });
+}
+
+export function pluginEntriesOfHome(
+  entries: readonly PluginLedgerEntry[],
+  opencliHome: string,
+): PluginLedgerEntry[] {
+  return entries.filter((entry) => entry.opencliHome === opencliHome);
+}
+
+export function isHeldEntry(entry: PluginLedgerEntry): boolean {
+  return entry.releasedAt === undefined;
+}
+
+export function heldEntriesOfHome(
+  entries: readonly PluginLedgerEntry[],
+  opencliHome: string,
+): PluginLedgerEntry[] {
+  return pluginEntriesOfHome(entries, opencliHome).filter(isHeldEntry);
+}
+
+export function heldEntryOfPlugin(
+  entries: readonly PluginLedgerEntry[],
+  opencliHome: string,
+  plugin: string,
+): PluginLedgerEntry | undefined {
+  const key = plugin.trim();
+  if (key === '') return undefined;
+  return heldEntriesOfHome(entries, opencliHome).find(
+    (entry) => entry.name === key || entry.package === key,
+  );
+}
+
+export function withReleasedEntry(
+  entries: readonly PluginLedgerEntry[],
+  opencliHome: string,
+  pkg: string,
+  releasedAt: string,
+): PluginLedgerEntry[] {
+  const entry = pluginEntryOf(entries, opencliHome, pkg);
+  if (entry === undefined || entry.releasedAt !== undefined) return [...entries];
+  return withPluginEntry(entries, { ...entry, releasedAt });
+}
+
+export type PluginRetention = 'remove' | 'keep-held' | 'keep-claimed' | 'keep-unsure';
+
+export function pluginRetentionOf(options: {
+  readonly held: boolean;
+  readonly claimedBy: readonly string[];
+  readonly trustworthy: boolean;
+}): PluginRetention {
+  if (options.held) return 'keep-held';
+  if (!options.trustworthy) return 'keep-unsure';
+  return options.claimedBy.length > 0 ? 'keep-claimed' : 'remove';
+}
+
+export function pluginEntryOf(
+  entries: readonly PluginLedgerEntry[],
+  opencliHome: string,
+  pkg: string,
+): PluginLedgerEntry | undefined {
+  const key = ledgerKeyOf({ opencliHome, package: pkg });
+  return entries.find((entry) => ledgerKeyOf(entry) === key);
+}
+
+export function withPluginEntry(
+  entries: readonly PluginLedgerEntry[],
+  entry: PluginLedgerEntry,
+): PluginLedgerEntry[] {
+  const key = ledgerKeyOf(entry);
+  return [...entries.filter((item) => ledgerKeyOf(item) !== key), entry];
+}
+
+export function withoutPluginEntry(
+  entries: readonly PluginLedgerEntry[],
+  opencliHome: string,
+  pkg: string,
+): PluginLedgerEntry[] {
+  const key = ledgerKeyOf({ opencliHome, package: pkg });
+  return entries.filter((entry) => ledgerKeyOf(entry) !== key);
+}

package/src/host/provision.ts

@@ -11,6 +11,8 @@ export const PROVISION_ACTIONS = [
   'remove-bundle',
   'cancel-install',
   'update-dependency',
+  'update-plugin',
+  'uninstall-plugin',
 ] as const satisfies readonly ProvisionAction[];
 
 export const DEPENDENCY_ACTIONS = ['update-dependency'] as const satisfies readonly ProvisionAction[];
@@ -32,6 +34,7 @@ export function provisionTargetOf(action: ProvisionAction): ProvisionTarget {
   if (action === 'update-dependency') return 'id';
   if (action === 'install-bundle') return 'spec';
   if (action === 'remove-bundle') return 'name';
+  if (action === 'update-plugin' || action === 'uninstall-plugin') return 'name';
   if (action === 'cancel-install') return 'requestId';
   return 'unit';
 }
@@ -74,6 +77,7 @@ function requestOf(action: ProvisionAction, value: string): ProvisionRequest {
   if (action === 'update-dependency') return { action, id: value };
   if (action === 'install-bundle') return { action, spec: value };
   if (action === 'remove-bundle') return { action, name: value };
+  if (action === 'update-plugin' || action === 'uninstall-plugin') return { action, name: value };
   if (action === 'cancel-install') return { action, requestId: value };
   return { action, unit: value };
 }

package/src/host/unit-face.ts

@@ -9,9 +9,11 @@ import type { ValueHandoff } from '../host/value-handoff.js';
 import type { WorkspaceStore } from '../host/workspace-store.js';
 
 export interface UnitMountDeps {
+  readonly manifest: UnitManifest;
   readonly ctx: DshHostContext;
   readonly logger?: { info?(message: string): void; warn?(message: string): void } | undefined;
   readonly manifests: () => readonly UnitManifest[];
+  readonly ownedUnits: () => readonly string[];
   readonly opencliCommand?: string;
   readonly store: WorkspaceStore;
   readonly values?: ValueHandoff | undefined;
@@ -60,7 +62,11 @@ export interface UnitMountResult {
   readonly needsApproval?: ApprovalPolicy | undefined;
 }
 
-export interface UnitHostFace {
-  readonly manifest: UnitManifest;
+export interface UnitModuleFace {
+  readonly unit: string;
   mount(deps: UnitMountDeps): UnitMountResult;
 }
+
+export interface UnitOwnedFace extends UnitModuleFace {
+  readonly manifest: UnitManifest;
+}

package/src/host.ts

@@ -1,6 +1,7 @@
 export * from './config/constants.js';
 export * from './api/context-ref.js';
 export * from './api/unit.js';
+export * from './api/unit-declaration.js';
 export * from './api/facts.js';
 export * from './api/long-task.js';
 export * from './lib/text.js';
@@ -16,6 +17,7 @@ export * from './host/http.js';
 export * from './host/long-task.js';
 export * from './host/opencli-runtime.js';
 export * from './host/opencli.js';
+export * from './host/plugin-ledger.js';
 export * from './host/plugin-source.js';
 export * from './host/provision.js';
 export * from './host/shell.js';

package/src/i18n/en.ts

@@ -70,7 +70,7 @@ export const en: Record<keyof WorkbenchMessages, string> = {
   'panels.market.missing': 'not installed',
   'panels.market.unchecked': 'unknown',
   'panels.market.checking': 'checking',
-  'panels.market.sectionInstalled': 'Installed',
+  'panels.market.sectionInstalled': 'Installed modules',
   'panels.market.sectionPending': 'Not installed',
   'panels.market.sectionShared': 'Shared dependencies',
   'panels.market.sharedUsedBy': 'Used by {modules}',
@@ -100,11 +100,19 @@ export const en: Record<keyof WorkbenchMessages, string> = {
   'panels.market.noSource': 'This module declares no install method — install it yourself',
   'panels.market.badSource': 'The install method is incomplete — install it yourself',
   'panels.market.empty': 'No modules available',
-  'panels.market.installedSection': 'Installed',
-  'panels.market.sectionLocal': 'Linked locally',
+  'panels.market.sectionLocal': 'Local modules',
   'panels.market.sectionUnlisted': 'Not from the market',
+  'panels.market.sectionPlugins': 'Installed opencli plugins',
   'panels.market.moduleOutdated': 'update available',
+  'panels.market.moduleRefused': 'This module was built for an older version of the workbench, so it does not work here. Update it, or uninstall.',
+  'panels.market.moduleRefusedDetail': 'Why it cannot be used: {reason}',
   'panels.market.moduleRestartHint': 'installed but not active — restart dsh once to bring it up',
+  'panels.market.pluginKeptInUse': 'Files kept for now: {names} still uses it.',
+  'panels.market.pluginKeptUnsure': 'Files kept for now: some modules on this machine do not say what they use, so it is unclear who needs it.',
+  'panels.market.pluginKeptHeld': 'Files kept: this one is yours, and a module letting go will not remove it.',
+  'panels.market.pluginKeptUnnamed': 'Files kept for now: this one cannot be identified as a plugin, so it is unclear who needs it.',
+  'panels.market.pluginAlsoKnownAs': 'Its package is {pkg} (updates and uninstall use that)',
+  'panels.market.pluginBroken': 'This install is broken: it cannot be identified as a plugin. Uninstall it, or install it again by package name above.',
   'panels.market.restartNeeded': 'The new version is installed — restart once to pick it up.',
   'panels.market.foot': 'After installing, enable it in the panel page of that project.',
   'panels.market.recheck': 'Check for updates',
@@ -152,7 +160,12 @@ export const en: Record<keyof WorkbenchMessages, string> = {
   'panels.market.add.problemInstalled': 'This module is already installed',
   'panels.market.add.problemNotFound': 'No such module found',
   'panels.market.add.problemNotPackage': 'That path does not exist or is not a valid module package',
-  'panels.market.add.problemNotBundle': 'This package declares no bundle, so it cannot be installed as a module: {reason}',
+  'panels.market.add.problemNotBundle':
+    'This package cannot be installed here: {reason}. If it is actually an opencli plugin, use its package name (for example opencli-plugin-cmdb) or a local folder — a git URL or tarball does not reveal what it is.',
+  'panels.market.add.problemNotWorkbenchModule': 'This package does not match the workbench you are running, so installing it would not work. Pick another version, or ask the module author.',
+  'panels.market.add.problemNotModuleOrPlugin': 'This package is neither a workbench module nor an opencli plugin, so installing it would do nothing. Pick another version, or ask the package author.',
+  'panels.market.add.failureNotModuleOrPlugin': 'This package is neither a workbench module nor an opencli plugin, so installing it would do nothing',
+  'panels.market.add.installedPlugin': 'Installed: the opencli plugin {name}',
   'panels.market.add.problemNetwork': 'Cannot reach the module source; check the network and retry',
   'panels.market.add.problemUnknown': 'Cannot fetch module information: {reason}',
   'panels.market.add.failureNetwork': 'The network connection failed',
@@ -183,6 +196,7 @@ export const en: Record<keyof WorkbenchMessages, string> = {
   'panels.market.add.registryPnpm': "pnpm's own registry",
   'panels.market.add.check': 'Check',
   'panels.market.add.checking': 'Checking…',
+  'panels.market.add.classifying': 'Working out what it is…',
   'panels.market.add.change': 'Edit',
   'panels.market.add.previewTitle': 'About to install',
   'panels.market.add.fieldName': 'Package',

package/src/i18n/zh.ts

@@ -68,7 +68,7 @@ export const zh = {
   'panels.market.missing': '未装',
   'panels.market.unchecked': '状态未知',
   'panels.market.checking': '检测中',
-  'panels.market.sectionInstalled': '已安装',
+  'panels.market.sectionInstalled': '已安装模块',
   'panels.market.sectionPending': '未安装',
   'panels.market.sectionShared': '共用依赖',
   'panels.market.sharedUsedBy': '供 {modules} 使用',
@@ -96,11 +96,19 @@ export const zh = {
   'panels.market.noSource': '这个模块没声明怎么装，只能自己动手',
   'panels.market.badSource': '安装方式没写全，只能自己动手',
   'panels.market.empty': '暂无可用模块',
-  'panels.market.installedSection': '已安装',
-  'panels.market.sectionLocal': '本地装的',
+  'panels.market.sectionLocal': '本地模块',
   'panels.market.sectionUnlisted': '不是从市场装的',
+  'panels.market.sectionPlugins': '已安装 opencli 插件',
   'panels.market.moduleOutdated': '有新版',
+  'panels.market.moduleRefused': '这个模块是给旧版本的工作台写的，现在用不了。更新它，或者卸载。',
+  'panels.market.moduleRefusedDetail': '装不上的原因：{reason}',
   'panels.market.moduleRestartHint': '装好了但还没生效 —— 重启一次 dsh 就会出来',
+  'panels.market.pluginKeptInUse': '文件先留着：{names} 还要用它。',
+  'panels.market.pluginKeptUnsure': '文件先留着：这台机器上还有模块看不出用了什么，说不准谁在用它。',
+  'panels.market.pluginKeptHeld': '文件留着：你自己装的那一份，模块放手不动它。',
+  'panels.market.pluginKeptUnnamed': '文件先留着：看不出这是哪个插件，说不准谁在用它。',
+  'panels.market.pluginAlsoKnownAs': '包名是 {pkg}（更新与卸载按它来）',
+  'panels.market.pluginBroken': '这份装坏了：看不出它是个插件。可以卸载，或者去上面按包名再装一次。',
   'panels.market.restartNeeded': '新版装好了，重启一次才生效。',
   'panels.market.foot': '装好后到那个项目的面板页勾选它，模块才会出现。',
   'panels.market.recheck': '重新检查更新',
@@ -148,7 +156,12 @@ export const zh = {
   'panels.market.add.problemInstalled': '该模块已安装',
   'panels.market.add.problemNotFound': '未找到相关模块',
   'panels.market.add.problemNotPackage': '该路径不存在或不是有效的模块包',
-  'panels.market.add.problemNotBundle': '这个包没有声明组合包，无法作为模块安装：{reason}',
+  'panels.market.add.problemNotBundle':
+    '这个包装不进这里：{reason}。要是它其实是个 opencli 插件，请改用包名（例如 opencli-plugin-cmdb）或者本地目录 —— 从 git 地址和 tarball 判断不出它是什么。',
+  'panels.market.add.problemNotWorkbenchModule': '这个包跟现在的工作台对不上，装上也用不了。换一个版本，或者找这个模块的作者。',
+  'panels.market.add.problemNotModuleOrPlugin': '这个包既不是工作台的模块，也不是 opencli 的插件，装了也用不上。换一个版本，或者找这个包的作者。',
+  'panels.market.add.failureNotModuleOrPlugin': '这个包既不是工作台的模块，也不是 opencli 的插件，装了也用不上',
+  'panels.market.add.installedPlugin': '装上了：opencli 插件 {name}',
   'panels.market.add.problemNetwork': '无法连接模块源，请检查网络后重试',
   'panels.market.add.problemUnknown': '无法获取模块信息：{reason}',
   'panels.market.add.failureNetwork': '网络连接失败',
@@ -179,6 +192,7 @@ export const zh = {
   'panels.market.add.registryPnpm': 'pnpm 自己配的源',
   'panels.market.add.check': '预检',
   'panels.market.add.checking': '正在预检…',
+  'panels.market.add.classifying': '判定中…',
   'panels.market.add.change': '改一下',
   'panels.market.add.previewTitle': '将要安装',
   'panels.market.add.fieldName': '包名',

package/src/index.ts

@@ -8,6 +8,7 @@ export * from './api/host-write.js';
 export * from './api/long-task.js';
 export * from './api/unit-board.js';
 export * from './api/unit.js';
+export * from './api/unit-declaration.js';
 export * from './api/workbench-client.js';
 export * from './api/workbench-contract.js';
 export * from './components/Activity.js';

package/src/testing/__tests__/declaration.test.ts

@@ -0,0 +1,48 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { declarationOfPackage } from '../declaration.js';
+
+const roots: string[] = [];
+
+function packageAt(manifest: unknown, text?: string): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'wb-declaration-'));
+  roots.push(root);
+  const at = path.join(root, 'package.json');
+  fs.writeFileSync(at, text ?? JSON.stringify({ name: '@t/demo', dsh: { workbench: manifest } }), 'utf8');
+  return at;
+}
+
+afterEach(() => {
+  for (const root of roots.splice(0)) fs.rmSync(root, { recursive: true, force: true });
+});
+
+const DECLARED = {
+  apiVersion: 1,
+  unit: 'demo',
+  card: { titleKey: 'demo.cardTitle', order: 7 },
+  tools: [{ name: 'workbench_demo_list', writes: false }],
+  host: { inject: [] },
+};
+
+describe('模块作者写用例时读自己那份声明', () => {
+  it('读出来的就是外壳会拿到的那份清单', () => {
+    const manifest = declarationOfPackage('@t/demo', packageAt(DECLARED));
+
+    expect(manifest.id).toBe('demo');
+    expect(manifest.card).toEqual({ titleKey: 'demo.cardTitle', order: 7 });
+    expect(manifest.tools).toEqual([{ name: 'workbench_demo_list', writes: false }]);
+  });
+
+  it('★ 声明有毛病就当场抛，并把 problems 原样带出来（别让用例拿着半个清单继续跑）', () => {
+    expect(() => declarationOfPackage('@t/demo', packageAt({ unit: 'demo' }))).toThrow(/apiVersion/);
+    expect(() =>
+      declarationOfPackage('@t/demo', packageAt({ ...DECLARED, faces: { host: 'src/host.ts' } })),
+    ).toThrow(/faces/);
+  });
+
+  it('package.json 本身读不动时也说清是哪个文件（不是一句 JSON 语法错）', () => {
+    expect(() => declarationOfPackage('@t/demo', packageAt({}, '{ 坏掉的'))).toThrow(/读不动/);
+  });
+});

package/src/testing/declaration.ts

@@ -0,0 +1,23 @@
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import type { UnitManifest } from '../api/unit.js';
+import { readDeclaration } from '../api/unit-declaration.js';
+
+export function declarationOfPackage(pkg: string, packageJson: URL | string): UnitManifest {
+  const at = typeof packageJson === 'string' ? packageJson : fileURLToPath(packageJson);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(fs.readFileSync(at, 'utf8'));
+  } catch (error) {
+    throw new Error(`${pkg}: 读不动 ${at} —— ${String(error)}`, { cause: error });
+  }
+  const declared =
+    typeof parsed === 'object' && parsed !== null
+      ? (parsed as { dsh?: { workbench?: unknown } }).dsh?.workbench
+      : undefined;
+  const read = readDeclaration(pkg, declared);
+  if (read.manifest === undefined) {
+    throw new Error(`${pkg} 的 dsh.workbench 读不出来：${read.problems.join('；')}`);
+  }
+  return read.manifest;
+}

package/src/testing.ts

@@ -1 +1,2 @@
 export * from './testing/host-fakes.js';
+export * from './testing/declaration.js';