@dsh-workbench/shared 1.0.1 → 1.1.0

package/src/contract/unit-declaration.ts

@@ -1,10 +1,11 @@
-import type { UnitHostNeeds, UnitManifest } from '../contract/unit.js';
+import type { UnitHostNeeds, UnitManifest, UnitTitle } from '../contract/unit.js';
+import { unitTitleKey } from '../contract/unit.js';
 import { needsProblemsOf, type Need } from './needs.js';
 
 /**
  * 声明协议当前版本；模块清单的 dsh.workbench.apiVersion 要写这个整数。
  */
-export const WORKBENCH_API_VERSION = 2;
+export const WORKBENCH_API_VERSION = 3;
 
 /**
  * 外壳愿意认的协议版本；不在表里的模块当场被拒，不猜语义。
@@ -12,10 +13,9 @@ export const WORKBENCH_API_VERSION = 2;
 export const SUPPORTED_API_VERSIONS: readonly number[] = [WORKBENCH_API_VERSION];
 
 /**
- * 清单里那半张卡片声明：文案键加排序位；卡片默认显不显示不在这里（那是运行期面板配置的事）。
+ * 清单里那半张卡片声明：只剩排序位；卡片默认显不显示不在这里（那是运行期面板配置的事）。
  */
 export interface UnitCardDeclaration {
-  readonly titleKey: string;
   readonly order: number;
 }
 
@@ -29,11 +29,12 @@ export interface UnitToolDeclaration {
 }
 
 /**
- * 模块清单里 dsh.workbench 那一段的完整形状（协议版本、单元 id、卡片、工具、宿主与环境需要）。
+ * 模块清单里 dsh.workbench 那一段的完整形状（协议版本、单元 id、名字、卡片、工具、宿主与环境需要）。
  */
 export interface UnitDeclaration {
   readonly apiVersion: number;
   readonly unit: string;
+  readonly title: UnitTitle;
   readonly card: UnitCardDeclaration | null;
   readonly tools: readonly UnitToolDeclaration[];
   readonly host: UnitHostNeeds;
@@ -46,6 +47,7 @@ export interface UnitDeclaration {
 export const DECLARATION_KEYS: readonly string[] = [
   'apiVersion',
   'unit',
+  'title',
   'card',
   'tools',
   'host',
@@ -58,12 +60,14 @@ export const DECLARATION_KEYS: readonly string[] = [
 export const DECLARATION_REQUIRED_KEYS: readonly string[] = [
   'apiVersion',
   'unit',
+  'title',
   'card',
   'tools',
   'host',
 ];
 
-const CARD_KEYS = ['titleKey', 'order'];
+const CARD_KEYS = ['order'];
+const TITLE_KEYS = ['zh', 'en'];
 const TOOL_KEYS = ['name', 'writes', 'key'];
 
 const TOOL_KEY_SHAPE = /^[a-z][a-zA-Z0-9]*$/;
@@ -77,6 +81,17 @@ function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
+/**
+ * 读一份声明里的协议版本；不是对象或 apiVersion 不是整数时给 undefined。
+ * @param raw 清单里 dsh.workbench 那段原始值。
+ * @returns 声明声明的协议版本，读不出来时 undefined。
+ */
+export function declarationApiVersionOf(raw: unknown): number | undefined {
+  if (!isRecord(raw)) return undefined;
+  const version = raw.apiVersion;
+  return Number.isInteger(version) ? (version as number) : undefined;
+}
+
 function outsideKeys(value: Readonly<Record<string, unknown>>, allowed: readonly string[]): string[] {
   return Object.keys(value).filter((key) => !allowed.includes(key));
 }
@@ -110,10 +125,9 @@ export function declarationProblemsOf(subject: string, raw: unknown): readonly s
   }
   if (!Number.isInteger(version) || !SUPPORTED_API_VERSIONS.includes(version as number)) {
     const hint =
-      version === 1
-        ? ` —— v2 把 \`env\` 的三张表（command / plugins / libs）换成了 \`needs\`：` +
-          '把外部需要逐条写成 `{ kind, name, purpose, ... }`（kind 是 bin / extension / lib / env），' +
-          '再把 apiVersion 改成 2'
+      version === 2
+        ? ' —— v3 把卡片标题挪成了顶层 `title`（`{ "zh": "…", "en": "…" }` 字面量）：' +
+          '把 `card.titleKey` 删掉、在顶层写 title，再把 apiVersion 改成 3'
         : '';
     return [
       `${subject}: dsh.workbench.apiVersion 是 ${JSON.stringify(version)}，这里只认 ` +
@@ -140,6 +154,29 @@ export function declarationProblemsOf(subject: string, raw: unknown): readonly s
     }
   }
 
+  const title = raw.title;
+  if (title !== undefined) {
+    if (!isRecord(title)) {
+      problems.push(
+        `${subject}: dsh.workbench.title 要是对象（中英各一份），现在是 ${JSON.stringify(title)}`,
+      );
+    } else {
+      const extra = outsideKeys(title, TITLE_KEYS);
+      if (extra.length > 0) {
+        problems.push(
+          `${subject}: dsh.workbench.title 里有不认的键 ${listOf(extra)} —— title 只有 ${listOf(TITLE_KEYS)}`,
+        );
+      }
+      for (const language of TITLE_KEYS) {
+        if (text(title[language]) === '') {
+          problems.push(
+            `${subject}: dsh.workbench.title.${language} 要是非空字符串（市场和面板里显示的名字）`,
+          );
+        }
+      }
+    }
+  }
+
   const card = raw.card;
   if (card !== undefined && card !== null) {
     if (!isRecord(card)) {
@@ -149,12 +186,9 @@ export function declarationProblemsOf(subject: string, raw: unknown): readonly s
       if (extra.length > 0) {
         problems.push(
           `${subject}: dsh.workbench.card 里有不认的键 ${listOf(extra)} —— card 只有 ${listOf(CARD_KEYS)}` +
-            `（卡片默认显不显示由运行期的面板配置决定，清单里没有这一位）`,
+            `（名字写在顶层的 title 里；卡片默认显不显示由运行期的面板配置决定，清单里没有这一位）`,
         );
       }
-      if (text(card.titleKey) === '') {
-        problems.push(`${subject}: dsh.workbench.card.titleKey 要是非空字符串（面板那一格的文案键）`);
-      }
       if (typeof card.order !== 'number' || !Number.isFinite(card.order)) {
         problems.push(`${subject}: dsh.workbench.card.order 要是数字，现在是 ${JSON.stringify(card.order)}`);
       }
@@ -257,16 +291,18 @@ export function readDeclaration(subject: string, raw: unknown): DeclarationRead
   const needsRead = needsProblemsOf(subject, declaration.needs);
   if (needsRead.errors.length > 0) return { problems: needsRead.errors, warnings: needsRead.warnings };
   const card = declaration.card;
+  const id = text(declaration.unit);
   return {
     declaration,
     problems: [],
     manifest: {
-      id: text(declaration.unit),
+      id,
+      title: { zh: text(declaration.title.zh), en: text(declaration.title.en) },
       card:
         card === null
           ? null
           : {
-              titleKey: text(card.titleKey),
+              titleKey: unitTitleKey(id),
               order: card.order,
             },
       tools: declaration.tools.map((tool) => ({

package/src/contract/unit.ts

@@ -1,5 +1,22 @@
 import type { ExtensionNeed, LibNeed, Need } from './needs.js';
 
+/**
+ * 模块的人类可读名字：中英各一份，写在 package.json 的 dsh.workbench.title 里。
+ */
+export interface UnitTitle {
+  readonly zh: string;
+  readonly en: string;
+}
+
+/**
+ * 外壳替模块名合成的词表键：模块自己不必写名字键，名字直接从清单里的 title 注册进来。
+ * @param unit 单元 id。
+ * @returns 该单元名字在词表里的键。
+ */
+export function unitTitleKey(unit: string): string {
+  return `dsh-workbench.unit.${unit}.title`;
+}
+
 /**
  * 一张卡片在清单里的静态声明（文案键加排序位）；默认显不显示由运行期面板配置定。
  */
@@ -33,10 +50,11 @@ export interface PluginRelease {
 }
 
 /**
- * 装配期用的模块清单：单元 id、卡片、工具、宿主服务与环境需要，比声明少一层协议包装。
+ * 装配期用的模块清单：单元 id、名字、卡片、工具、宿主服务与环境需要，比声明少一层协议包装。
  */
 export interface UnitManifest {
   readonly id: string;
+  readonly title?: UnitTitle;
   readonly card: UnitCard | null;
   readonly tools: readonly UnitTool[];
   readonly host: UnitHostNeeds;

package/src/contract/workbench-contract.ts

@@ -15,7 +15,9 @@ export type ProvisionAction =
   | 'cancel-install'
   | 'update-plugin'
   | 'uninstall-plugin'
-  | 'update-workbench';
+  | 'update-workbench'
+  | 'migrate-workbench'
+  | 'dismiss-followup';
 
 /**
  * 宿主对「这个单元现在能不能用」的那份读数：状态汇总加逐条 need 的细节。

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

@@ -16,6 +16,8 @@ describe('provision 请求体：每类动作各有各的目标字段', () => {
       ['update-plugin', 'name'],
       ['uninstall-plugin', 'name'],
       ['update-workbench', 'name'],
+      ['migrate-workbench', 'name'],
+      ['dismiss-followup', 'id'],
     ]);
   });
 

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

@@ -2,12 +2,16 @@ 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 {
+function npm(
+  pkg?: string,
+  registryEnv = 'DSH_WB_REGISTRY',
+  registryDefault = 'https://registry.invalid/',
+): SupplySource {
   return {
     kind: 'npm',
     ...(pkg === undefined ? {} : { package: pkg }),
     registryEnv,
-    registryDefault: 'https://registry.invalid/',
+    registryDefault,
   };
 }
 
@@ -77,23 +81,55 @@ describe('供给索引：一个包只有一个来源', () => {
     expect(index.sourcesOf('extension', 'coding')).toEqual([npm('opencli-plugin-coding')]);
   });
 
-  it('★★ 共用库两家用不同的 registryEnv：判冲突，即使地址相同', () => {
+  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).toEqual([]);
+    expect(index.entryOf('lib', 'opencli-workflow')?.conflicted).toBe(false);
+    expect(index.entryOf('lib', 'opencli-workflow')?.declarers).toEqual(['argocd', 'cmdb']);
+    expect(index.sourcesOf('lib', 'opencli-workflow')).toHaveLength(1);
+  });
+
+  it('★★ registryEnv 名不同、其中一家被环境变量指到别处：判冲突', () => {
+    const index = buildSupplyIndex(
+      [
+        manifest('jenkins', [lib('opencli-workflow', [npm(undefined, 'DSH_WB_JENKINS_REGISTRY')])]),
+        manifest('argocd', [lib('opencli-workflow', [npm(undefined, 'DSH_WB_ARGOCD_REGISTRY')])]),
+      ],
+      { env: { DSH_WB_JENKINS_REGISTRY: 'https://mirror.invalid/' } },
+    );
+
+    expect(index.conflicts.map((item) => item.kind)).toEqual(['source-mismatch']);
+    expect(index.sourcesOf('lib', 'opencli-workflow')).toEqual([]);
+  });
+
+  it('★★ 两家默认源就不同：判冲突，哪怕 registryEnv 同名', () => {
+    const index = buildSupplyIndex([
+      manifest('a', [lib('opencli-workflow', [npm(undefined, 'DSH_WB_REGISTRY', 'https://r-a.invalid/')])]),
+      manifest('b', [lib('opencli-workflow', [npm(undefined, 'DSH_WB_REGISTRY', 'https://r-b.invalid/')])]),
+    ]);
+
     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('★ 两家都没写默认源、registryEnv 又不同：解析不出地址，按名字判冲突', () => {
+    const index = buildSupplyIndex([
+      manifest('a', [lib('opencli-workflow', [{ kind: 'npm', registryEnv: 'DSH_WB_A_REGISTRY' }])]),
+      manifest('b', [lib('opencli-workflow', [{ kind: 'npm', registryEnv: 'DSH_WB_B_REGISTRY' }])]),
+    ]);
+
+    expect(index.conflicts).toHaveLength(1);
   });
 
   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')])]),
+      manifest('c', [lib('opencli-workflow', [npm(undefined, 'DSH_WB_C_REGISTRY', 'https://mirror.invalid/')])]),
     ]);
 
     expect(index.conflicts).toHaveLength(1);

package/src/host/provision.ts

@@ -15,6 +15,8 @@ export const PROVISION_ACTIONS = [
   'update-plugin',
   'uninstall-plugin',
   'update-workbench',
+  'migrate-workbench',
+  'dismiss-followup',
 ] as const satisfies readonly ProvisionAction[];
 
 export const DEPENDENCY_ACTIONS = ['update-dependency'] as const satisfies readonly ProvisionAction[];
@@ -37,7 +39,8 @@ export function provisionTargetOf(action: ProvisionAction): ProvisionTarget {
   if (action === 'install-bundle' || action === 'install-version') return 'spec';
   if (action === 'remove-bundle') return 'name';
   if (action === 'update-plugin' || action === 'uninstall-plugin') return 'name';
-  if (action === 'update-workbench') return 'name';
+  if (action === 'update-workbench' || action === 'migrate-workbench') return 'name';
+  if (action === 'dismiss-followup') return 'id';
   if (action === 'cancel-install') return 'requestId';
   return 'unit';
 }
@@ -81,7 +84,8 @@ function requestOf(action: ProvisionAction, value: string): ProvisionRequest {
   if (action === 'install-bundle' || action === 'install-version') 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 === 'update-workbench') return { action, name: value };
+  if (action === 'update-workbench' || action === 'migrate-workbench') return { action, name: value };
+  if (action === 'dismiss-followup') return { action, id: value };
   if (action === 'cancel-install') return { action, requestId: value };
   return { action, unit: value };
 }

package/src/host/supply-index.ts

@@ -1,10 +1,15 @@
 import type { ExtensionNeed, LibNeed, Need, SupplySource } from '../contract/needs.js';
+import { npmRegistryOf } from './plugin-source.js';
 
 export interface SupplyDeclaration {
   readonly id: string;
   readonly needs?: readonly Need[];
 }
 
+export interface SupplyIndexOptions {
+  readonly env?: Readonly<Record<string, string | undefined>>;
+}
+
 export interface SupplyEntry {
   readonly key: string;
   readonly kind: 'extension' | 'lib';
@@ -81,16 +86,28 @@ function keyOf(kind: 'extension' | 'lib', pkg: string): string {
   return `${kind}:${pkg}`;
 }
 
-function sourceCompatible(left: SupplySource, right: SupplySource): boolean {
+function registryAddressOf(
+  source: Extract<SupplySource, { kind: 'npm' }>,
+  env: Readonly<Record<string, string | undefined>>,
+): string | undefined {
+  const resolved = npmRegistryOf(source, env);
+  return resolved.ok ? resolved.value : undefined;
+}
+
+function sourceCompatible(
+  left: SupplySource,
+  right: SupplySource,
+  env: Readonly<Record<string, string | undefined>>,
+): boolean {
   if (left.kind !== right.kind) return false;
   if (left.kind === 'npm' && right.kind === 'npm') {
     if (text(left.package) !== '' && text(right.package) !== '' && text(left.package) !== text(right.package)) {
       return false;
     }
-    if (text(left.registryEnv) !== text(right.registryEnv)) return false;
-    const l = text(left.registryDefault);
-    const r = text(right.registryDefault);
-    return l === '' || r === '' || l === r;
+    const l = registryAddressOf(left, env);
+    const r = registryAddressOf(right, env);
+    if (l !== undefined && r !== undefined) return l === r;
+    return text(left.registryEnv) === text(right.registryEnv);
   }
   if (left.kind === 'git' && right.kind === 'git') return text(left.url) === text(right.url);
   if (left.kind === 'local' && right.kind === 'local') {
@@ -99,11 +116,15 @@ function sourceCompatible(left: SupplySource, right: SupplySource): boolean {
   return false;
 }
 
-function sourcesCompatible(left: readonly SupplySource[], right: readonly SupplySource[]): boolean {
+function sourcesCompatible(
+  left: readonly SupplySource[],
+  right: readonly SupplySource[],
+  env: Readonly<Record<string, string | undefined>>,
+): boolean {
   if (left.length !== right.length) return false;
   return left.every((source, index) => {
     const other = right[index];
-    return other !== undefined && sourceCompatible(source, other);
+    return other !== undefined && sourceCompatible(source, other, env);
   });
 }
 
@@ -120,13 +141,17 @@ function mergedSource(left: SupplySource, right: SupplySource): SupplySource {
   return left;
 }
 
-function mergeSources(entry: MutableEntry, sources: readonly SupplySource[]): boolean {
+function mergeSources(
+  entry: MutableEntry,
+  sources: readonly SupplySource[],
+  env: Readonly<Record<string, string | undefined>>,
+): boolean {
   if (!entry.declared) {
     entry.declared = true;
     entry.sources = [...sources];
     return true;
   }
-  if (!sourcesCompatible(entry.sources, sources)) {
+  if (!sourcesCompatible(entry.sources, sources, env)) {
     entry.conflicted = true;
     return false;
   }
@@ -150,7 +175,11 @@ function addDeclarer(entry: MutableEntry, unit: string, commands: readonly strin
   for (const command of commands) if (!entry.commands.includes(command)) entry.commands.push(command);
 }
 
-export function buildSupplyIndex(declarations: readonly SupplyDeclaration[]): SupplyIndex {
+export function buildSupplyIndex(
+  declarations: readonly SupplyDeclaration[],
+  options: SupplyIndexOptions = {},
+): SupplyIndex {
+  const env = options.env ?? {};
   const entries = new Map<string, MutableEntry>();
   const byName = new Map<string, MutableEntry>();
   const conflicts: SupplyConflict[] = [];
@@ -186,7 +215,7 @@ export function buildSupplyIndex(declarations: readonly SupplyDeclaration[]): Su
       } else {
         addDeclarer(entry, declaration.id, []);
       }
-      const same = mergeSources(entry, need.sources ?? []);
+      const same = mergeSources(entry, need.sources ?? [], env);
       if (!same) {
         conflicts.push({
           kind: 'source-mismatch',