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

package/src/components/ChoiceGroup.css

@@ -1,4 +1,3 @@
-
 .wb-choiceMenu {
   display: flex;
   flex-direction: column;
@@ -180,4 +179,4 @@
 .wb-radio:focus-visible {
   outline: var(--dsw-focus-ring-width, var(--wb-len-2)) solid var(--dsw-focus-ring-color, var(--dsw-alias-state-business-primary));
   outline-offset: 2px;
-}
+}

package/src/components/ConfirmBar.tsx

@@ -29,7 +29,7 @@ export interface ConfirmBarProps {
 
 /**
  * 「先问一句再动手」那一条：标题 + 说明 + 键值 + 失败那句 + 动作区，形状一次收口。
- * **要不要问**归调用点（ADR-0054 §2 规则三），这一件只回答"问的时候长什么样"。
+ * **要不要问**归调用点，这一件只回答"问的时候长什么样"。
  * @param props.title - 那一句问话（"发布到 prod？"）。
  * @param props.hint - 标题下面那句说明或正文；不给不占位。
  * @param props.rows - 键值两格（键值列宽与分隔线归 `Rows` / `Row`）；不给或空数组不渲染。值那一格可以放控件。

package/src/components/Form.css

@@ -3,4 +3,4 @@
   flex-direction: column;
   gap: var(--wb-len-12);
   width: 100%;
-}
+}

package/src/components/Form.tsx

@@ -77,4 +77,4 @@ export function Form<Values extends object = FormValues>(props: FormProps<Values
       />
     </form>
   );
-}
+}

package/src/components/FormActions.tsx

@@ -46,7 +46,7 @@ function reportExtraPrimaries(actions: readonly FormAction[]): void {
   if (keys.length < 2) return;
   console.error(
     `[dsh-workbench] FormActions 一个区里出现了 ${keys.length} 颗 primary（${keys.join('、')}）—— ` +
-      '一个区只许一颗主操作（ADR-0054 §2 规则二）：多余的这颗该改成 default',
+      '一个区只许一颗主操作：多余的这颗该改成 default',
   );
 }
 

package/src/components/LongTaskRow.css

@@ -1,4 +1,3 @@
-
 .wb-longTask {
   padding-top: var(--wb-len-12);
   border-top: 0.5px solid var(--dsw-alias-border-l2);
@@ -97,4 +96,4 @@
   line-height: var(--wb-line-16);
   color: var(--dsw-alias-state-error-primary);
   overflow-wrap: anywhere;
-}
+}

package/src/components/LongTaskRow.tsx

@@ -1,4 +1,4 @@
-import { longTaskDot, longTaskStopPress, longTaskStopStage, LONG_TASK_STOP_ARM_MS, type LongTaskStatus } from '../api/long-task.js';
+import { longTaskDot, longTaskStopPress, longTaskStopStage, LONG_TASK_STOP_ARM_MS, type LongTaskStatus } from '../contract/long-task.js';
 import { Link } from './Link.js';
 import { Fragment, h, useEffect, useState } from '../lib/react.js';
 import {

package/src/components/Note.css

@@ -1,4 +1,3 @@
-
 .wb-note {
   margin: 0;
   font-size: var(--dsw-font-xxs-12-font-size);

package/src/components/ResourceStates.css

@@ -1,4 +1,3 @@
-
 .wb-centered.wb-centeredCompact {
   flex: none;
   min-height: 0;

package/src/components/SelectFieldNodes.tsx

@@ -98,4 +98,3 @@ export function selectLoadingNode(args: {
     </button>
   );
 }
-

package/src/components/SettingsSection.css

@@ -1,4 +1,3 @@
-
 section.wb-settings {
   display: flex;
   flex-direction: column;

package/src/components/Spinner.css

@@ -1,4 +1,3 @@
-
 .wb-spinner {
   display: inline-flex;
   align-items: center;

package/src/components/Stack.css

@@ -1,4 +1,3 @@
-
 .wb-stack {
   display: flex;
   flex-direction: column;

package/src/components/StateBlock.css

@@ -1,4 +1,3 @@
-
 .wb-stateBlock {
   display: flex;
   flex-direction: column;

package/src/components/__tests__/long-task-row.test.ts

@@ -43,7 +43,7 @@ describe('两按停止钮：接线（这仓的组件测试是 node 环境，读
   });
 
   it('★★ 上膛后 3 秒自己落膛：用 LONG_TASK_STOP_ARM_MS，卸载 / 落膛都清掉计时器', () => {
-    expect(ROW).toContain("from '../api/long-task.js'");
+    expect(ROW).toContain("from '../contract/long-task.js'");
     expect(ROW).toContain('setTimeout(() => setArmed(false), LONG_TASK_STOP_ARM_MS)');
     expect(ROW).toContain('clearTimeout(timer)');
     expect(ROW).toContain('}, [armed]);');

package/src/components/board-module.ts

@@ -1,7 +1,7 @@
 import type { ReactNode } from 'react';
-import type { SessionsSnapshot, Translate, WorkspaceSnapshot, WorkspaceView } from '../api/dsh-client.js';
-import type { UnitManifest } from '../api/unit.js';
-import type { CapabilityPayload } from '../api/workbench-contract.js';
+import type { SessionsSnapshot, Translate, WorkspaceSnapshot, WorkspaceView } from '../lib/dsh-client.js';
+import type { UnitManifest } from '../contract/unit.js';
+import type { CapabilityPayload } from '../contract/workbench-contract.js';
 import type { Dictionaries } from '../i18n/index.js';
 
 /**

package/src/components/icons.tsx

@@ -51,20 +51,28 @@ export function IconConversation({ size = 16 }: IconProps) {
   );
 }
 
+const BRAND_FRAME = 'M10 6H54A5 5 0 0 1 59 11V43A5 5 0 0 1 54 48H10A5 5 0 0 1 5 43V11A5 5 0 0 1 10 6Z M12 10H52A3 3 0 0 1 55 13V41A3 3 0 0 1 52 44H12A3 3 0 0 1 9 41V13A3 3 0 0 1 12 10Z';
+
+const BRAND_TAIL =
+  'M8.844 13.742C8.967 12.328 8.45 10.4 8.45 9.65C8.45 8.94 8.88 8.43 9.6 8.43C11.285 8.43 12.106 8.281 12.685 8.104C13.71 7.791 14.585 6.768 15.055 5.945C15.137 5.803 14.99 5.641 14.829 5.671C13.829 5.86 12.828 5.376 11.827 4.978C10.659 4.514 9.491 4.707 8.935 4.876C8.805 4.915 8.658 4.819 8.636 4.686C8.468 3.643 7.405 2.615 5.498 2.238C4.54 2.048 3.748 1.574 3.347 1.202C3.252 1.113 3.088 1.125 3.03 1.242C2.628 2.059 2.168 3.82 5.248 6.115C5.82 6.494 6.31 6.785 6.574 7.637C6.72 8.104 6.157 9.168 6.061 9.368C5.157 11.27 5.089 12.19 4.926 13.742Z';
+
+const BRAND_TAIL_TRANSFORM = 'translate(14.6263 10.5853) scale(1.95)';
+
 /**
- * 品牌标：侧栏顶上那枚工作台方块标；默认 24px（它是品牌物，别拿它当通用图标）。
+ * 品牌标：一台显示器里放着 dsh 的鲸鱼尾巴；默认 24px（它是品牌物，别拿它当通用图标）。
  * @param props.size - 边长像素，同时给 `width` 与 `height`。
  * @returns 一枚 `aria-hidden` 的 svg。
  */
 export function IconBrandMark({ size = 24 }: IconProps) {
   return (
-    <Shell size={size} strokeWidth={1.6} viewBox="0 0 24 24">
-      <rect x={3} y={3} width={18} height={18} rx={5} stroke="currentColor" />
-      <path
-        d="M8 9.5h8M8 12.5h8M8 15.5h5"
-        stroke="currentColor"
-        strokeLinecap="round"
-      />
+    <Shell size={size} viewBox="0 0 64 64">
+      <path d={BRAND_FRAME} fill="currentColor" fillRule="evenodd" />
+      <rect x={27.5} y={48} width={9} height={4.75} fill="currentColor" />
+      <rect x={19} y={52.75} width={26} height={4.75} rx={2.375} fill="currentColor" />
+      <g transform={BRAND_TAIL_TRANSFORM}>
+        <path d={BRAND_TAIL} fill="currentColor" />
+        <circle cx={6.885} cy={13.742} r={1.95} fill="currentColor" />
+      </g>
     </Shell>
   );
 }
@@ -117,22 +125,6 @@ export function IconNpm({ size = 16 }: IconProps) {
   );
 }
 
-/**
- * 四宫格："模块"这个概念的通用单色图标（侧栏、面板那颗钮、市场节的标题）；默认 16px。
- * @param props.size - 边长像素，同时给 `width` 与 `height`。
- * @returns 一枚 `aria-hidden` 的 svg。
- */
-export function IconModules({ size = 16 }: IconProps) {
-  return (
-    <svg width={size} height={size} viewBox="0 0 16 16" fill="none" aria-hidden="true">
-      <rect x="2.5" y="2.5" width="4.6" height="4.6" rx="1.2" stroke="currentColor" strokeWidth="1.2" />
-      <rect x="8.9" y="2.5" width="4.6" height="4.6" rx="1.2" stroke="currentColor" strokeWidth="1.2" />
-      <rect x="2.5" y="8.9" width="4.6" height="4.6" rx="1.2" stroke="currentColor" strokeWidth="1.2" />
-      <rect x="8.9" y="8.9" width="4.6" height="4.6" rx="1.2" stroke="currentColor" strokeWidth="1.2" />
-    </svg>
-  );
-}
-
 /**
  * 模块类型标：渐变方块 + 白四宫格，用在"这是个模块"的行首；品牌物，颜色不跟主题走。默认 16px。
  * @param props.size - 边长像素，同时给 `width` 与 `height`。

package/src/config/constants.ts

@@ -40,8 +40,8 @@ export const PANEL_STATE_PREFIX = `${API_PREFIX}/${PANEL_STATE_PATH}`;
 /** 钉住的 opencli 插件版本：`opencli-runtime` 按它校验、取那一份。 */
 export const OPENCLI_PIN = "1.8.8";
 
-/** 缺陷看板套件的 dsh 服务名（`workbenchCodingIssues`）：套件照它登记自己那份服务。 */
-export const CODING_ISSUES_SERVICE = "workbenchCodingIssues";
+/** 缺陷看板套件的 dsh 服务名（`workbenchIssues`）：套件照它登记自己那份服务。 */
+export const ISSUES_SERVICE = "workbenchIssues";
 
 /** 面板套件的 dsh 服务名（`workbenchPanels`）：宿主经它取套件公布的清单与订阅。 */
 export const PANELS_SERVICE = "workbenchPanels";

package/src/config/storage.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import { readFlag, readText, writeFlag, writeText } from './storage.js';
+import { readText, writeText } from './storage.js';
 
 function fakeStorage(options: { throwOnWrite?: boolean } = {}) {
   const data = new Map<string, string>();
@@ -44,30 +44,6 @@ describe('storage', () => {
     expect(fake.data.has('k')).toBe(false);
   });
 
-  it('没存过时读回 null / 默认值', () => {
-    useStorage();
-    expect(readText('missing')).toBeNull();
-    expect(readFlag('missing', true)).toBe(true);
-    expect(readFlag('missing', false)).toBe(false);
-  });
-
-  it('布尔开关按字面量往返', () => {
-    useStorage();
-    writeFlag('on', true);
-    writeFlag('off', false);
-    expect(readFlag('on', false)).toBe(true);
-    expect(readFlag('off', true)).toBe(false);
-  });
-
-  it('只有字面量 "true" 算真：脏数据不因为"非空"就把开关打开', () => {
-    useStorage();
-    writeText('weird', 'yes');
-    writeText('one', '1');
-    expect(readFlag('weird', true)).toBe(false);
-    expect(readFlag('one', true)).toBe(false);
-    expect(readFlag('never', true)).toBe(true);
-  });
-
   it('localStorage 抛异常时静默降级（隐私模式不该让面板崩掉）', () => {
     useStorage({ throwOnWrite: true });
     expect(() => writeText('k', 'v')).not.toThrow();

package/src/config/storage.ts

@@ -15,15 +15,3 @@ export function writeText(key: string, value: string | null): void {
   } catch {
   }
 }
-
-/** 读一个布尔开关：键不存在时返回 `fallback`，只有存进去的 `'true'` 算真。 */
-export function readFlag(key: string, fallback: boolean): boolean {
-  const raw = readText(key);
-  if (raw === null) return fallback;
-  return raw === 'true';
-}
-
-/** 把一个布尔开关写进 localStorage（存 `'true'` / `'false'`）；失败静默。 */
-export function writeFlag(key: string, value: boolean): void {
-  writeText(key, value ? 'true' : 'false');
-}

package/src/{api → contract}/__tests__/facts.test.ts

@@ -5,6 +5,7 @@ import {
   parseFactFrame,
   type FactFrame,
   type FactTransport,
+  type FactTransportMode,
 } from '../facts.js';
 
 function fakeTransport(): {
@@ -52,17 +53,17 @@ describe('createFactChannel', () => {
   it('★ 之后的帧只惊动它点名的事实（别的读者不该白跑一次）', () => {
     const wire = fakeTransport();
     const channel = createFactChannel({ transport: wire.transport });
-    const cmdb = vi.fn();
+    const inventory = vi.fn();
     const issues = vi.fn();
-    channel.subscribe('cmdb/summary', cmdb);
+    channel.subscribe('inventory/summary', inventory);
     channel.subscribe('issues', issues);
     channel.applyFrame({ epoch: 'e1', rev: 1, facts: [] });
 
-    channel.applyFrame({ epoch: 'e1', rev: 2, facts: ['cmdb/summary'] });
+    channel.applyFrame({ epoch: 'e1', rev: 2, facts: ['inventory/summary'] });
 
-    expect(cmdb).toHaveBeenCalledTimes(1);
+    expect(inventory).toHaveBeenCalledTimes(1);
     expect(issues).not.toHaveBeenCalled();
-    expect(channel.revisionOf('cmdb/summary')).toBe(2);
+    expect(channel.revisionOf('inventory/summary')).toBe(2);
     expect(channel.revisionOf('issues')).toBe(0);
   });
 
@@ -132,33 +133,33 @@ describe('createFactChannel', () => {
     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.subscribe('inventory/summary', summary);
+    channel.subscribe('inventory/builds?env=innettest', builds);
+    channel.subscribe('issues/list', issues);
     channel.applyFrame({ epoch: 'e1', rev: 1, facts: [] });
 
-    channel.applyFrame({ epoch: 'e1', rev: 2, facts: ['capability', 'panels', 'cmdb*'] });
+    channel.applyFrame({ epoch: 'e1', rev: 2, facts: ['capability', 'panels', 'inventory*'] });
 
     expect(summary).toHaveBeenCalledTimes(1);
     expect(builds).toHaveBeenCalledTimes(1);
     expect(issues).not.toHaveBeenCalled();
-    expect(channel.revisionOf('cmdb/summary')).toBeGreaterThan(1);
+    expect(channel.revisionOf('inventory/summary')).toBeGreaterThan(1);
   });
 
   it('命名空间不许凭空造出订阅（订阅表只由读者写），也不许越界到别的模块', () => {
     const wire = fakeTransport();
     const channel = createFactChannel({ transport: wire.transport });
-    const codingAnalysis = vi.fn();
+    const demoAnalysis = vi.fn();
     const lookalike = vi.fn();
-    channel.subscribe('coding-analysis/summary', codingAnalysis);
-    channel.subscribe('cmdb-extra/summary', lookalike);
+    channel.subscribe('analysis/summary', demoAnalysis);
+    channel.subscribe('inventory-extra/summary', lookalike);
     channel.applyFrame({ epoch: 'e1', rev: 1, facts: [] });
 
-    channel.applyFrame({ epoch: 'e1', rev: 2, facts: ['cmdb*'] });
+    channel.applyFrame({ epoch: 'e1', rev: 2, facts: ['inventory*'] });
 
-    expect(codingAnalysis).not.toHaveBeenCalled();
+    expect(demoAnalysis).not.toHaveBeenCalled();
     expect(lookalike).not.toHaveBeenCalled();
-    expect(channel.revisionOf('cmdb/never-subscribed')).toBe(0);
+    expect(channel.revisionOf('inventory/never-subscribed')).toBe(0);
     expect(channel.subscriberCount()).toBe(2);
   });
 
@@ -166,26 +167,26 @@ describe('createFactChannel', () => {
     const wire = fakeTransport();
     const channel = createFactChannel({ transport: wire.transport });
     const listener = vi.fn();
-    channel.subscribe('cmdb/builds?env=innettest', listener);
+    channel.subscribe('inventory/builds?env=innettest', listener);
 
-    channel.applyFrame({ epoch: 'e1', rev: 4, facts: ['cmdb*'] });
+    channel.applyFrame({ epoch: 'e1', rev: 4, facts: ['inventory*'] });
 
     expect(listener).not.toHaveBeenCalled();
-    expect(channel.revisionOf('cmdb/builds?env=innettest')).toBeGreaterThan(0);
+    expect(channel.revisionOf('inventory/builds?env=innettest')).toBeGreaterThan(0);
   });
 
   it('refresh(命名空间) 只惊动它下面的事实（本地失效也按模块点名，不是一律全量）', () => {
     const wire = fakeTransport();
     const channel = createFactChannel({ transport: wire.transport });
-    const cmdb = vi.fn();
+    const inventory = vi.fn();
     const issues = vi.fn();
-    channel.subscribe('cmdb/summary', cmdb);
-    channel.subscribe('coding-issues/list', issues);
+    channel.subscribe('inventory/summary', inventory);
+    channel.subscribe('issues/list', issues);
     channel.applyFrame({ epoch: 'e1', rev: 1, facts: [] });
 
-    channel.refresh('cmdb*');
+    channel.refresh('inventory*');
 
-    expect(cmdb).toHaveBeenCalledTimes(1);
+    expect(inventory).toHaveBeenCalledTimes(1);
     expect(issues).not.toHaveBeenCalled();
   });
 
@@ -204,6 +205,53 @@ describe('createFactChannel', () => {
 
     expect(seen).toEqual([4]);
   });
+
+  it('★ 传输来路：没建连是 null，报上来就换档，同一档不重复惊动', () => {
+    const wire: { report: ((mode: FactTransportMode) => void) | null } = { report: null };
+    const channel = createFactChannel({
+      transport: {
+        start(handlers) {
+          wire.report = handlers.onMode ?? null;
+          return () => {};
+        },
+      },
+    });
+    const listener = vi.fn();
+    expect(channel.mode()).toBeNull();
+    channel.subscribeMode(listener);
+    channel.subscribe('panels', vi.fn());
+
+    wire.report?.('polling');
+    expect(channel.mode()).toBe('polling');
+    wire.report?.('polling');
+    expect(listener).toHaveBeenCalledTimes(1);
+
+    wire.report?.('sse');
+    expect(channel.mode()).toBe('sse');
+    expect(listener).toHaveBeenCalledTimes(2);
+  });
+
+  it('★ 最后一个订阅走掉、传输停了，来路回到没建连', () => {
+    const wire: { report: ((mode: FactTransportMode) => void) | null } = { report: null };
+    const channel = createFactChannel({
+      transport: {
+        start(handlers) {
+          wire.report = handlers.onMode ?? null;
+          return () => {};
+        },
+      },
+    });
+    const listener = vi.fn();
+    channel.subscribeMode(listener);
+    const off = channel.subscribe('panels', vi.fn());
+    wire.report?.('sse');
+    listener.mockClear();
+
+    off();
+
+    expect(channel.mode()).toBeNull();
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
 });
 
 describe('parseFactFrame', () => {
@@ -255,7 +303,7 @@ describe('parseFactFrame', () => {
 
 describe('factOfRoute', () => {
   it('事实名就是路由名（不另起一套词汇，读与订阅不可能各说各话）', () => {
-    expect(factOfRoute('cmdb/summary')).toBe('cmdb/summary');
+    expect(factOfRoute('inventory/summary')).toBe('inventory/summary');
     expect(factOfRoute('capability')).toBe('capability');
   });
 });

package/src/{api → contract}/__tests__/long-task.test.ts

@@ -13,16 +13,16 @@ import {
 
 describe('runsRouteOf', () => {
   it('★ 事实名 = 路由名（三处同一个来源，改一处不可能漏另一处）', () => {
-    expect(runsRouteOf('cmdb')).toBe('cmdb/runs');
+    expect(runsRouteOf('inventory')).toBe('inventory/runs');
     expect(runsRouteOf('issues')).toBe('issues/runs');
   });
 });
 
 describe('stopRouteOf（停止那条写路由）', () => {
   it('★ 就是读路由 + `/stop`（读口与写口同一个单元名，不另造一套命名）', () => {
-    expect(stopRouteOf('cmdb')).toBe('cmdb/runs/stop');
+    expect(stopRouteOf('inventory')).toBe('inventory/runs/stop');
     expect(stopRouteOf('issues')).toBe('issues/runs/stop');
-    expect(stopRouteOf('cmdb')).toBe(`${runsRouteOf('cmdb')}/stop`);
+    expect(stopRouteOf('inventory')).toBe(`${runsRouteOf('inventory')}/stop`);
   });
 });
 

package/src/contract/__tests__/needs.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'vitest';
+import {
+  NEED_KINDS,
+  NEED_KIND_SPECS,
+  SUPPLY_SOURCE_KINDS,
+  needProblemsOf,
+  needsProblemsOf,
+} from '../needs.js';
+
+const npm = { kind: 'npm', package: '@acme/plugin-demo', registryDefault: 'https://registry.test/' };
+const base = { kind: 'lib', name: 'demo', purpose: '测试', sources: [npm] };
+
+function errorsOf(need: unknown): readonly string[] {
+  return needProblemsOf('demo', need, 0).errors;
+}
+
+describe('needs 校验矩阵', () => {
+  it('★ 四种 kind 的最小声明都过；注册表与 NEED_KINDS 一一对应', () => {
+    expect(
+      needsProblemsOf('demo', [
+        { kind: 'bin', name: 'gitops', purpose: '部署' },
+        { kind: 'extension', runtime: 'opencli', name: 'demo', purpose: '面板', sources: [npm] },
+        base,
+        { kind: 'env', name: 'DSH_TOKEN', secret: true, purpose: '只读接口' },
+      ]).errors,
+    ).toEqual([]);
+    expect(Object.keys(NEED_KIND_SPECS).sort()).toEqual([...NEED_KINDS].sort());
+  });
+
+  it('未知 kind / 未知 source.kind → 红，并点名', () => {
+    const unknownKind = errorsOf({ kind: 'mcp', name: 'x', purpose: '测试' });
+    expect(unknownKind.join(' ')).toContain('needs[0].kind 不认识');
+    const unknownSource = errorsOf({ ...base, sources: [{ kind: 'tarball', url: 'x' }] });
+    expect(unknownSource.join(' ')).toContain('sources[0].kind 不认识');
+    expect(new Set(Object.values(NEED_KIND_SPECS).flatMap((spec) => spec.sources))).toEqual(
+      new Set(SUPPLY_SOURCE_KINDS),
+    );
+  });
+
+  it('bin / env 写了 sources → 红（没有安装路径）', () => {
+    expect(errorsOf({ kind: 'bin', name: 'x', purpose: '测试', sources: [npm] }).join(' ')).toContain(
+      '不支持 sources',
+    );
+    expect(errorsOf({ kind: 'env', name: 'X', purpose: '测试', sources: [npm] }).join(' ')).toContain(
+      '不支持 sources',
+    );
+  });
+
+  it('lib 只认 npm 源；sources 空数组 → 红（不代装就整条删掉）', () => {
+    expect(errorsOf({ ...base, sources: [{ kind: 'git', url: 'github:acme/demo' }] }).join(' ')).toContain(
+      '只支持 npm',
+    );
+    expect(errorsOf({ ...base, sources: [] }).join(' ')).toContain('空数组');
+  });
+
+  it('必填项：purpose、extension.runtime、name、required 类型、id 空串', () => {
+    expect(errorsOf({ ...base, purpose: '' }).join(' ')).toContain('purpose 没写');
+    expect(errorsOf({ kind: 'extension', name: 'x', purpose: '测试' }).join(' ')).toContain('runtime 没写');
+    expect(errorsOf({ ...base, name: '' }).join(' ')).toContain('name 没写');
+    expect(errorsOf({ ...base, required: 'yes' }).join(' ')).toContain('required 要是布尔');
+    expect(errorsOf({ ...base, id: '' }).join(' ')).toContain('id 是空串');
+  });
+
+  it('★ need 内未知字段只是警告；x- 前缀直接忽略（不为可选字段升协议版本）', () => {
+    const read = needProblemsOf('demo', { ...base, future: 1, 'x-vendor': true }, 0);
+    expect(read.errors).toEqual([]);
+    expect(read.warnings.join(' ')).toContain('不认识的字段 future');
+    expect(read.warnings.join(' ')).not.toContain('x-vendor');
+  });
+
+  it('没写 needs → 空表不报', () => {
+    expect(needsProblemsOf('demo', undefined)).toEqual({ errors: [], warnings: [] });
+  });
+});

package/src/{host → contract}/__tests__/unit-declaration.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest';
 import { declarationProblemsOf, readDeclaration } from '../unit-declaration.js';
 
 const declared = (tools: unknown) => ({
-  apiVersion: 1,
+  apiVersion: 2,
   unit: 'demo',
   card: null,
   tools,

package/src/contract/__tests__/unit.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import type { Need } from '../needs.js';
+import { needsOf, provisionableNeedsOf, type UnitManifest } from '../unit.js';
+
+function manifest(needs?: readonly Need[]): UnitManifest {
+  return {
+    id: 'issues',
+    card: { titleKey: 'issues.mine', order: 10 },
+    tools: [],
+    host: { inject: [] },
+    ...(needs === undefined ? {} : { needs }),
+  };
+}
+
+const npm = { kind: 'npm' as const, registryEnv: 'WB_NPM', registryDefault: 'https://registry.example/' };
+
+describe('provisionableNeedsOf（缺来源时那条回退口径，宿主与浏览器共用一份）', () => {
+  it('写了 sources 的 extension / lib → 宿主可代装', () => {
+    const needs: Need[] = [
+      { kind: 'extension', runtime: 'opencli', name: 'demo', purpose: '测试', sources: [npm] },
+      { kind: 'lib', name: 'opencli-workflow', purpose: '测试', sources: [npm] },
+    ];
+    expect(provisionableNeedsOf(manifest(needs)).map((need) => need.name)).toEqual([
+      'demo',
+      'opencli-workflow',
+    ]);
+  });
+
+  it('★ 没写 sources 的 extension、bin、env 都不算供给 —— 它们不是市场门槛，只是「我自己装，你帮我判」', () => {
+    const needs: Need[] = [
+      { kind: 'extension', runtime: 'opencli', name: 'demo', purpose: '测试' },
+      { kind: 'bin', name: 'gitops', purpose: '测试' },
+      { kind: 'env', name: 'DSH_TOKEN', purpose: '测试' },
+    ];
+    expect(provisionableNeedsOf(manifest(needs))).toEqual([]);
+    expect(provisionableNeedsOf(manifest([]))).toEqual([]);
+    expect(provisionableNeedsOf(manifest())).toEqual([]);
+  });
+
+  it('needsOf 没写就是空表', () => {
+    expect(needsOf(manifest())).toEqual([]);
+  });
+});

package/src/contract/adapters.ts

@@ -0,0 +1,9 @@
+export interface BrowserPort {
+  read(input: unknown): Promise<unknown>;
+  find(input: unknown): Promise<unknown>;
+}
+
+export interface PreflightPort {
+  run(options?: { readonly hard?: boolean }): Promise<unknown>;
+  snapshot(): unknown;
+}

package/src/contract/cli.ts

@@ -0,0 +1,3 @@
+export interface CliPort {
+  readonly command: string;
+}