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

package/src/components/FormNodes.tsx

@@ -193,6 +193,7 @@ export function formRowsOf<Values extends object>(args: {
     h(FormRow, {
       key: field.key,
       label: field.label,
+      htmlFor: controlIdOf(field.key),
       hint: field.hint,
       problem: args.showProblem ? args.problems[field.key] : undefined,
       layout: field.layout,
@@ -200,6 +201,10 @@ export function formRowsOf<Values extends object>(args: {
   );
 }
 
+function controlIdOf(key: string): string {
+  return `wb-form-${key}`;
+}
+
 function controlOf<K extends string, V, Vals extends object>(
   field: FormField<K, V, Vals>,
   problems: Readonly<Record<string, ReactNode | undefined>>,
@@ -207,7 +212,7 @@ function controlOf<K extends string, V, Vals extends object>(
   busy: boolean,
 ): ReactNode {
   return field.control({
-    id: `wb-form-${field.key}`,
+    id: controlIdOf(field.key),
     name: field.key,
     invalid: showProblem && Boolean(problems[field.key]),
     disabled: busy || field.disabled === true,

package/src/components/FormRows.css

@@ -29,6 +29,7 @@
 }
 
 .wb-formLabel {
+  justify-self: start;
   min-width: 0;
   font-size: var(--dsw-font-xs-13-font-size);
   color: var(--dsw-alias-label-secondary);

package/src/components/FormRows.test.tsx

@@ -48,6 +48,35 @@ describe('FormRow', () => {
     expect(childrenOf(node).filter((one) => one !== null)).toHaveLength(2);
   });
 
+  it('★ 行是 <div>，<label> 只包标签文字 —— 控件、提示与整行空白都不在标签里', () => {
+    const node = FormRow({
+      label: '项目',
+      htmlFor: 'wb-form-project',
+      hint: '选错了也能改',
+      children: '下拉',
+    }) as unknown as { type: unknown; props: { children: unknown[] } };
+    const [labelNode, controlNode, hintNode] = node.props.children as {
+      type: unknown;
+      props: Record<string, unknown>;
+    }[];
+
+    expect(node.type).toBe('div');
+    expect(labelNode?.type).toBe('label');
+    expect(labelNode?.props['htmlFor']).toBe('wb-form-project');
+    expect(texts(labelNode)).toEqual(['项目']);
+    expect(controlNode?.props['className']).toBe('wb-formControl');
+    expect(hintNode?.props['className']).toBe('wb-formHint');
+  });
+
+  it('没给 htmlFor 就不挂 for（排布照旧，只是点标签不聚焦）', () => {
+    const node = FormRow({ label: '项目', children: '下拉' }) as unknown as {
+      props: { children: unknown[] };
+    };
+    const labelNode = node.props.children[0] as { props: Record<string, unknown> };
+
+    expect(labelNode.props['htmlFor']).toBeUndefined();
+  });
+
   it('有 problem 就顶掉 hint（同一格，二选一），错误行挂 data-wb-problem 给聚焦那件找', () => {
     const node = FormRow({
       label: '项目',
@@ -150,6 +179,7 @@ describe('标签列：同一个 FormRows 共用一列（ADR-0052 §11）', () =>
 
   it('★ 标签不折行；stacked 还是单列、标签照常换行', () => {
     expect(declarations('.wb-formLabel')).toContain('white-space: nowrap');
+    expect(declarations('.wb-formLabel')).toContain('justify-self: start');
     expect(declarations(".wb-formRow[data-layout='stacked'] .wb-formLabel")).toContain(
       'white-space: normal',
     );

package/src/components/FormRows.tsx

@@ -23,6 +23,7 @@ export function FormRows({ children }: FormRowsProps) {
  */
 export interface FormRowProps {
   readonly label: ReactNode;
+  readonly htmlFor?: string | undefined;
   readonly hint?: ReactNode | undefined;
   readonly problem?: ReactNode | undefined;
   readonly layout?: 'inline' | 'stacked' | undefined;
@@ -32,20 +33,23 @@ export interface FormRowProps {
 /**
  * 表单一行：左边标签、右边控件，提示与错误占控件下面那一格。
  * @param props.label - 这一行的标签；进了这一行，控件自己就别再给 `label`，否则会多一个标签。
+ * @param props.htmlFor - 标签挂到哪个控件（同一个 `id`）；不给就只是排布，点标签不聚焦 —— `Form` 会自己接好。
  * @param props.hint - 控件下的说明；给了 `problem` 就不画它 —— 同一格不叠两段话。
  * @param props.problem - 校验失败那句话；给了就顶掉 `hint` 并给整行加上出错标记。
  * @param props.layout - `stacked` 才是标签在上、控件在下（默认 `inline`：标签在左）。
  * @param props.children - 控件本体。
- * @returns 一个 `<label>`。
+ * @returns 一个 `<div>`：里面的 `<label>` 只包标签文字，不包控件、提示与整行的空白。
  */
-export function FormRow({ label, hint, problem, layout = 'inline', children }: FormRowProps) {
+export function FormRow({ label, htmlFor, hint, problem, layout = 'inline', children }: FormRowProps) {
   return (
-    <label
+    <div
       className="wb-formRow"
       data-layout={layout}
       data-wb-problem={problem === undefined ? undefined : ''}
     >
-      <span className="wb-formLabel">{label}</span>
+      <label className="wb-formLabel" htmlFor={htmlFor}>
+        {label}
+      </label>
       <span className="wb-formControl">{children}</span>
       {problem === undefined ? (
         hint === undefined ? null : (
@@ -54,6 +58,6 @@ export function FormRow({ label, hint, problem, layout = 'inline', children }: F
       ) : (
         <span className="wb-formProblem">{problem}</span>
       )}
-    </label>
+    </div>
   );
 }

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

package/src/config/constants.ts

@@ -1,12 +1,6 @@
 /** 外壳插件的包名：浏览器模块表与宿主按它注册、认领这枚插件。 */
 export const PLUGIN_ID = "@dsh-workbench/core";
 
-/** 与外壳同批发布的兄弟包名：`release.ts` 用它判一版三包是否都已在源上。 */
-export const RELEASE_SIBLINGS = [
-  "@dsh-workbench/shared",
-  "@dsh-workbench/module-tools",
-] as const;
-
 /** 外壳宿主 HTTP API 的根前缀；prefs / actions / provision 等路由都挂在它下面。 */
 export const API_PREFIX = "/workbench/api";
 
@@ -40,8 +34,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/{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;
+}

package/src/contract/command.ts

@@ -0,0 +1,25 @@
+export interface CommandFile {
+  readonly content: string;
+  readonly suffix?: string | undefined;
+}
+
+export interface CommandRequest {
+  readonly argv: readonly string[];
+  readonly timeoutMs?: number | undefined;
+  readonly cwd?: string | undefined;
+  readonly files?: readonly CommandFile[] | undefined;
+  readonly appendFileArgs?: string | undefined;
+}
+
+export interface CommandResult {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly exitCode: number;
+  readonly timedOut: boolean;
+  readonly filePaths: readonly string[];
+  readonly error?: string | undefined;
+}
+
+export interface CommandReader {
+  run(request: CommandRequest): Promise<CommandResult>;
+}