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

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

@@ -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/{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/data.ts

@@ -0,0 +1,145 @@
+export interface DataRequestBase {
+  readonly timeoutMs?: number;
+}
+
+export interface HttpDataRequest extends DataRequestBase {
+  readonly kind: 'http';
+  readonly url: string;
+  readonly headers?: Readonly<Record<string, string>>;
+}
+
+export interface BrowserDataRequest extends DataRequestBase {
+  readonly kind: 'browser';
+  readonly script: string;
+  readonly url?: string;
+  readonly loginUrl?: string;
+  readonly session?: string;
+  readonly open?: boolean;
+}
+
+export interface CommandDataRequest extends DataRequestBase {
+  readonly kind: 'command';
+  readonly command: string;
+}
+
+export type DataRequest = HttpDataRequest | BrowserDataRequest | CommandDataRequest;
+
+export type DataErrorCode = 'invalid-request' | 'http' | 'auth' | 'timeout' | 'parse' | 'command' | 'browser';
+
+export interface DataError {
+  readonly code: DataErrorCode;
+  readonly message: string;
+  readonly status?: number;
+  readonly detail?: string;
+  readonly hint?: string;
+  readonly helpUrl?: string;
+  readonly pageCode?: string;
+}
+
+export interface DataSuccess<T = unknown> {
+  readonly ok: true;
+  readonly data: T;
+}
+
+export interface DataFailure {
+  readonly ok: false;
+  readonly error: DataError;
+}
+
+export type DataResult<T = unknown> = DataSuccess<T> | DataFailure;
+
+export interface CredentialSourceCookie {
+  readonly kind: 'cookie';
+}
+
+export interface CredentialSourceCookieValue {
+  readonly kind: 'cookieValue';
+  readonly name: string;
+}
+
+export interface CredentialSourceEndpoint {
+  readonly kind: 'endpoint';
+  readonly url: string;
+  readonly method?: 'GET' | 'POST';
+  readonly body?: unknown;
+  readonly path: string;
+}
+
+export interface CredentialSourceMeta {
+  readonly kind: 'meta';
+  readonly name: string;
+}
+
+export interface CredentialSourceGlobal {
+  readonly kind: 'global';
+  readonly path: string;
+}
+
+export interface CredentialSourceStorage {
+  readonly kind: 'storage';
+  readonly area: 'local' | 'session';
+  readonly key: string;
+  readonly path?: string;
+}
+
+export type CredentialSource =
+  | CredentialSourceCookie
+  | CredentialSourceCookieValue
+  | CredentialSourceEndpoint
+  | CredentialSourceMeta
+  | CredentialSourceGlobal
+  | CredentialSourceStorage;
+
+export type CredentialPlace =
+  | { readonly in: 'cookie' }
+  | { readonly in: 'header'; readonly name: string; readonly prefix?: string }
+  | { readonly in: 'query'; readonly name: string }
+  | { readonly in: 'body'; readonly field: string };
+
+export type RecipeAuth =
+  | { readonly kind: 'none' }
+  | { readonly kind?: undefined; readonly source: CredentialSource; readonly place: CredentialPlace };
+
+export interface RecipeRequest {
+  readonly method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  readonly path: string;
+  readonly query?: Readonly<Record<string, string | number | boolean>>;
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly body?: unknown;
+  readonly contentType?: 'json' | 'form';
+}
+
+export interface RecipeResponse {
+  readonly kind: 'json' | 'text';
+  readonly path?: string;
+  readonly maxBytes?: number;
+}
+
+export interface RequestRecipe {
+  readonly origin: string;
+  readonly loginUrl?: string;
+  readonly session?: string;
+  readonly timeoutMs?: number;
+  readonly auth?: RecipeAuth;
+  readonly request: RecipeRequest;
+  readonly response?: RecipeResponse;
+}
+
+export interface CallOverrides {
+  readonly path?: string;
+  readonly query?: Readonly<Record<string, string | number | boolean>>;
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly body?: unknown;
+  readonly response?: Partial<RecipeResponse>;
+}
+
+export type RecipeCalls = Readonly<Record<string, CallOverrides>>;
+
+export type RecipeResults<T = unknown> = Readonly<Record<string, DataResult<T>>>;
+
+export interface DataReader {
+  read<T = unknown>(request: DataRequest): Promise<DataResult<T>>;
+  request<T = unknown>(recipe: RequestRecipe, overrides?: CallOverrides): Promise<DataResult<T>>;
+  requestMany<T = unknown>(recipe: RequestRecipe, calls: RecipeCalls): Promise<RecipeResults<T>>;
+  submit<T = unknown>(recipe: RequestRecipe, overrides?: CallOverrides): Promise<DataResult<T>>;
+}