@dsh-workbench/shared 0.1.0

package/src/api/facts.ts

@@ -0,0 +1,166 @@
+export interface FactFrame {
+  readonly epoch?: string;
+  readonly rev: number;
+  readonly facts: readonly string[];
+}
+
+export const FACT_SCOPE_SUFFIX = '*';
+
+export function unitFactScope(unit: string): string {
+  return `${unit}${FACT_SCOPE_SUFFIX}`;
+}
+
+export function isFactScope(name: string): boolean {
+  return name.length > 1 && name.endsWith(FACT_SCOPE_SUFFIX);
+}
+
+export function scopePrefixOf(name: string): string {
+  return isFactScope(name) ? name.slice(0, -FACT_SCOPE_SUFFIX.length) : name;
+}
+
+export interface FactTransport {
+  start(handlers: { readonly onFrame: (frame: FactFrame) => void; readonly cursor: () => number }): () => void;
+}
+
+export interface FactChannel {
+  subscribe(fact: string, listener: () => void): () => void;
+  revisionOf(fact: string): number;
+  refresh(fact?: string): void;
+  applyFrame(frame: FactFrame): void;
+  subscriberCount(): number;
+}
+
+interface FactEntry {
+  rev: number;
+  readonly listeners: Set<() => void>;
+}
+
+export function createFactChannel(options: { readonly transport: FactTransport }): FactChannel {
+  const entries = new Map<string, FactEntry>();
+  let epoch: string | null = null;
+  let stopTransport: (() => void) | null = null;
+  let hostRev = 0;
+  let generation = 0;
+
+  const entryOf = (fact: string): FactEntry => {
+    const existing = entries.get(fact);
+    if (existing !== undefined) return existing;
+    const created: FactEntry = { rev: 0, listeners: new Set() };
+    entries.set(fact, created);
+    return created;
+  };
+
+  const targetsOf = (fact: string): FactEntry[] => {
+    if (!isFactScope(fact)) {
+      const entry = entries.get(fact);
+      return entry === undefined ? [] : [entry];
+    }
+    const prefix = scopePrefixOf(fact);
+    const matched: FactEntry[] = [];
+    for (const [name, entry] of entries) {
+      if (name === prefix || name.startsWith(`${prefix}/`)) matched.push(entry);
+    }
+    return matched;
+  };
+
+  const mark = (fact: string, rev: number): void => {
+    if (!isFactScope(fact)) {
+      entryOf(fact).rev = rev;
+      return;
+    }
+    for (const entry of targetsOf(fact)) entry.rev = rev;
+  };
+
+  const notify = (facts: Iterable<string>): void => {
+    for (const fact of facts) {
+      for (const entry of targetsOf(fact)) {
+        for (const listener of [...entry.listeners]) listener();
+      }
+    }
+  };
+
+  const ensureTransport = (): void => {
+    if (stopTransport !== null) return;
+    stopTransport = options.transport.start({
+      onFrame: (frame) => channel.applyFrame(frame),
+      cursor: () => hostRev,
+    });
+  };
+
+  const releaseTransport = (): void => {
+    if (stopTransport === null) return;
+    stopTransport();
+    stopTransport = null;
+  };
+
+  const channel: FactChannel = {
+    revisionOf: (fact) => entries.get(fact)?.rev ?? 0,
+    subscribe(fact, listener) {
+      const entry = entryOf(fact);
+      entry.listeners.add(listener);
+      ensureTransport();
+      return () => {
+        entry.listeners.delete(listener);
+        if (channel.subscriberCount() === 0) releaseTransport();
+      };
+    },
+    subscriberCount() {
+      let count = 0;
+      for (const entry of entries.values()) count += entry.listeners.size;
+      return count;
+    },
+    refresh(fact) {
+      generation += 1;
+      if (fact === undefined) {
+        for (const entry of entries.values()) entry.rev = generation;
+        notify(entries.keys());
+        return;
+      }
+      mark(fact, generation);
+      notify([fact]);
+    },
+    applyFrame(frame) {
+      const nextEpoch = frame.epoch ?? null;
+      const first = epoch === null;
+      const epochChanged = epoch !== null && nextEpoch !== null && epoch !== nextEpoch;
+      if (nextEpoch !== null) epoch = nextEpoch;
+      hostRev = epochChanged ? frame.rev : Math.max(hostRev, frame.rev);
+      if (first) {
+        generation += 1;
+        for (const fact of frame.facts) mark(fact, generation);
+        return;
+      }
+      if (epochChanged) {
+        generation += 1;
+        for (const entry of entries.values()) entry.rev = generation;
+        notify(entries.keys());
+        return;
+      }
+      if (frame.facts.length === 0) return;
+      generation += 1;
+      for (const fact of frame.facts) mark(fact, generation);
+      notify(frame.facts);
+    },
+  };
+
+  return channel;
+}
+
+export function parseFactFrame(data: unknown): FactFrame | null {
+  if (typeof data !== 'string') return null;
+  try {
+    const parsed = JSON.parse(data) as { epoch?: unknown; rev?: unknown; facts?: unknown };
+    if (typeof parsed.rev !== 'number') return null;
+    return {
+      ...(typeof parsed.epoch === 'string' ? { epoch: parsed.epoch } : {}),
+      rev: parsed.rev,
+      facts: Array.isArray(parsed.facts) ? parsed.facts.filter((f): f is string => typeof f === 'string') : [],
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function factOfRoute(route: string): string {
+  return route;
+}

package/src/api/host-write.ts

@@ -0,0 +1,27 @@
+import type { ApiResponse } from './workbench-client';
+
+export type WriteChannel = 'prefs' | 'actions' | 'provision';
+
+export function writeRoute(channel: WriteChannel, resource: string): string {
+  if (channel === 'provision') return 'provision';
+  return `${channel}/${resource}`;
+}
+
+export type WriteOutcome<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly message: string; readonly detail?: string };
+
+export function writeOutcomeOf<T>(response: ApiResponse<T> | null, networkText: string): WriteOutcome<T> {
+  if (response === null) return { ok: false, message: networkText };
+  if (!response.ok) {
+    const box = response as {
+      readonly error?: { readonly message?: unknown; readonly detail?: unknown } | undefined;
+      readonly text?: unknown;
+    };
+    const own = typeof box.error?.message === 'string' && box.error.message !== '' ? box.error.message : undefined;
+    const fallback = typeof box.text === 'string' && box.text !== '' ? box.text : networkText;
+    const detail = typeof box.error?.detail === 'string' ? box.error.detail : undefined;
+    return { ok: false, message: own ?? fallback, ...(detail === undefined ? {} : { detail }) };
+  }
+  return { ok: true, value: response };
+}

package/src/api/long-task.ts

@@ -0,0 +1,38 @@
+export type LongTaskStatus = 'running' | 'needs-login' | 'ok' | 'failed';
+
+export interface LongTaskStep {
+  readonly kind: 'start' | 'succeed' | 'fail' | 'info' | 'warn';
+  readonly text: string;
+  readonly loginUrl?: string | undefined;
+}
+
+export function runsRouteOf(unit: string): string {
+  return `${unit}/runs`;
+}
+
+export interface LongTasksPayload {
+  readonly runs: readonly Readonly<Record<string, unknown>>[];
+}
+
+export const LONG_TASK_POLL_MS = 1500;
+
+export const LONG_TASK_IDLE_MS = 10_000;
+
+export function longTaskPollMs(live: boolean, override?: number | undefined): number {
+  if (override !== undefined) return override;
+  return live ? LONG_TASK_POLL_MS : LONG_TASK_IDLE_MS;
+}
+
+export function longTaskRunsOf<T>(state: {
+  readonly phase?: string | undefined;
+  readonly value?: LongTasksPayload | undefined;
+}): readonly T[] {
+  return (state.value?.runs ?? []) as readonly T[];
+}
+
+export function longTaskDot(status: LongTaskStatus): 'ongoing' | 'done' | 'error' | 'idle' {
+  if (status === 'ok') return 'done';
+  if (status === 'failed') return 'error';
+  if (status === 'running' || status === 'needs-login') return 'ongoing';
+  return 'idle';
+}

package/src/api/unit-board.ts

@@ -0,0 +1,44 @@
+import type { ModuleBlocker } from './blocker';
+import type { CapabilityPayload } from './workbench-contract';
+import type { ApiError } from './workbench-client';
+
+export type GateMode =
+  | 'capability'
+  | 'none';
+
+export interface UnitGate {
+  readonly gated: boolean;
+}
+
+export function gateOf(capability: CapabilityPayload | null, mode: GateMode): UnitGate {
+  if (mode === 'none') return { gated: true };
+  if (capability === null) return { gated: true };
+  return { gated: capability.status === 'ok' || capability.status === 'unchecked' };
+}
+
+export interface UnitBlockers {
+  readonly blocker?: ModuleBlocker;
+  readonly notice?: ModuleBlocker;
+}
+
+export function splitBlocker(candidates: readonly (ModuleBlocker | undefined)[]): UnitBlockers {
+  let blocker: ModuleBlocker | undefined;
+  let notice: ModuleBlocker | undefined;
+  for (const candidate of candidates) {
+    if (candidate === undefined) continue;
+    if (candidate.severity === 'block') {
+      blocker ??= candidate;
+      continue;
+    }
+    notice ??= candidate;
+  }
+  return {
+    ...(blocker === undefined ? {} : { blocker }),
+    ...(blocker !== undefined || notice === undefined ? {} : { notice }),
+  };
+}
+
+export function probeKeyOf(error: ApiError | undefined): string | null {
+  if (error === undefined) return null;
+  return error.code === '' ? 'unknown' : error.code;
+}

package/src/api/unit.ts

@@ -0,0 +1,59 @@
+export interface UnitCard {
+  readonly titleKey: string;
+  readonly order: number;
+  readonly enabledByDefault: boolean;
+}
+
+export interface UnitTool {
+  readonly name: string;
+  readonly writes: boolean;
+}
+
+export interface UnitHostNeeds {
+  readonly inject: readonly string[];
+  readonly optional?: readonly string[];
+}
+
+export type PluginSource =
+  | { readonly kind: 'git'; readonly url: string }
+  | { readonly kind: 'local'; readonly env: string }
+  | {
+      readonly kind: 'npm';
+      readonly package: string;
+      readonly registryEnv: string;
+      readonly registryDefault?: string;
+    };
+
+export interface UnitPluginNeed {
+  readonly name: string;
+  readonly commands?: readonly string[];
+  readonly installSource?: PluginSource;
+}
+
+export interface UnitLibNeed {
+  readonly name: string;
+  readonly version?: string | undefined;
+  readonly registryEnv: string;
+  readonly registryDefault: string;
+  readonly purpose: string;
+}
+
+export interface UnitEnvNeeds {
+  readonly command?: string;
+  readonly plugins?: readonly UnitPluginNeed[];
+  readonly libs?: readonly UnitLibNeed[];
+}
+
+export interface PluginRelease {
+  readonly installed: string;
+  readonly latest?: string;
+}
+
+export interface UnitManifest {
+  readonly id: string;
+  readonly kind: 'board' | 'ui';
+  readonly card: UnitCard | null;
+  readonly tools: readonly UnitTool[];
+  readonly host: UnitHostNeeds;
+  readonly env?: UnitEnvNeeds;
+}

package/src/api/workbench-client.test.ts

@@ -0,0 +1,92 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { API_PREFIX } from '../config/constants.js';
+import { apiGet } from './workbench-client';
+
+interface FetchRecord {
+  url: string;
+  method: string;
+}
+
+function stubFetch(reply: { status?: number; body: unknown }) {
+  const records: FetchRecord[] = [];
+  const fetchMock = vi.fn(async (url: string, init?: { method?: string }) => {
+    records.push({ url, method: init?.method ?? 'GET' });
+    return {
+      ok: (reply.status ?? 200) < 400,
+      status: reply.status ?? 200,
+      json: async () => reply.body,
+    };
+  });
+  vi.stubGlobal('fetch', fetchMock);
+  return { records, fetchMock };
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('apiGet', () => {
+  it('用 GET 打 API_PREFIX 下的路由，并带上 accept 头', async () => {
+    const { records, fetchMock } = stubFetch({ body: { ok: true } });
+    await apiGet('health');
+
+    expect(records[0]?.url).toBe(`${API_PREFIX}/health`);
+    expect(records[0]?.method).toBe('GET');
+    expect(fetchMock.mock.calls[0]?.[1]).toMatchObject({
+      method: 'GET',
+      headers: { accept: 'application/json' },
+    });
+  });
+
+  it('查询参数进 URL；undefined 的项不出现', async () => {
+    const { records } = stubFetch({ body: { ok: true } });
+    await apiGet('issues', { workspaceId: 'w1', status: 'all', refresh: undefined, n: 0 });
+
+    const [pathname, query] = (records[0]?.url ?? '').split('?');
+    const params = new URLSearchParams(query ?? '');
+    expect(pathname).toBe(`${API_PREFIX}/issues`);
+    expect(params.get('workspaceId')).toBe('w1');
+    expect(params.get('status')).toBe('all');
+    expect(params.get('n')).toBe('0');
+    expect(params.has('refresh')).toBe(false);
+  });
+
+  it('没有参数时不带问号', async () => {
+    const { records } = stubFetch({ body: { ok: true } });
+    await apiGet('project');
+    expect(records[0]?.url).toBe(`${API_PREFIX}/project`);
+  });
+
+  it('宿主的 {ok:true} 信封原样返回', async () => {
+    stubFetch({ body: { ok: true, issues: [{ code: 1 }] } });
+    const result = await apiGet<{ issues: Array<{ code: number }> }>('issues');
+    expect(result.ok).toBe(true);
+    expect(result.ok && result.issues[0]?.code).toBe(1);
+  });
+
+  it('宿主的 {ok:false} 信封原样返回，不抛异常', async () => {
+    stubFetch({
+      body: { ok: false, error: { code: 'coding-not-logged-in', message: '登录态失效' } },
+    });
+    const result = await apiGet('issues');
+    expect(result.ok).toBe(false);
+    expect(result.ok === false && result.error.code).toBe('coding-not-logged-in');
+  });
+
+  it('HTTP 非 2xx 也走结构化错误（不读 body）', async () => {
+    stubFetch({ status: 500, body: {} });
+    const result = await apiGet('issues');
+    expect(result.ok).toBe(false);
+    expect(result.ok === false && result.error).toMatchObject({ code: 'http' });
+    expect(result.ok === false && result.error.message).toContain('500');
+  });
+});
+
+describe('apiGet 不带任何"刷新鲜度"的开关', () => {
+  it('请求就是请求：没有 refresh 之类的旁路参数（宿主侧也没有缓存可绕）', async () => {
+    const { records } = stubFetch({ body: { ok: true } });
+    await apiGet('issues', { status: 'all' }, { signal: undefined });
+
+    expect(records[0]?.url).not.toContain('refresh');
+  });
+});

package/src/api/workbench-client.ts

@@ -0,0 +1,59 @@
+import { API_PREFIX } from '../config/constants.js';
+
+export interface ApiError {
+  readonly code: string;
+  readonly message: string;
+  readonly detail?: string;
+  readonly hint?: string;
+  readonly helpUrl?: string;
+}
+
+export type ApiResponse<T> = ({ readonly ok: true } & T) | { readonly ok: false; readonly error: ApiError };
+
+export type Query = Record<string, string | number | boolean | undefined>;
+
+export interface ApiGetOptions {
+  readonly signal?: AbortSignal | undefined;
+}
+
+export async function apiGet<T>(
+  route: string,
+  query: Query = {},
+  options: ApiGetOptions = {},
+): Promise<ApiResponse<T>> {
+  const { signal } = options;
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== undefined) search.set(key, String(value));
+  }
+  const suffix = search.toString();
+
+  const response = await fetch(`${API_PREFIX}/${route}${suffix ? `?${suffix}` : ''}`, {
+    method: 'GET',
+    headers: { accept: 'application/json' },
+    ...(signal === undefined ? {} : { signal }),
+  });
+
+  if (!response.ok) {
+    return {
+      ok: false,
+      error: { code: 'http', message: `宿主返回 HTTP ${response.status}` },
+    };
+  }
+
+  return (await response.json()) as ApiResponse<T>;
+}
+
+export async function apiPost<T>(route: string, body: Record<string, unknown>): Promise<ApiResponse<T>> {
+  const response = await fetch(`${API_PREFIX}/${route}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', accept: 'application/json' },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    return { ok: false, error: { code: 'http', message: `宿主返回 HTTP ${response.status}` } };
+  }
+
+  return (await response.json()) as ApiResponse<T>;
+}

package/src/api/workbench-contract.ts

@@ -0,0 +1,40 @@
+import type { PluginRelease } from '../api/unit.js';
+
+export type ProvisionAction =
+  | 'install'
+  | 'update'
+  | 'uninstall'
+  | 'update-dependency';
+
+export interface PluginStatePayload {
+  readonly name: string;
+  readonly status: 'ok' | 'outdated' | 'missing';
+  readonly missing: readonly string[];
+  readonly install?: 'ready' | 'not-declared' | 'env-missing' | 'malformed';
+  readonly command?: string;
+  readonly release?: PluginRelease;
+}
+
+export interface CapabilityPayload {
+  readonly unit: string;
+  readonly status: 'ok' | 'missing-commands' | 'missing-plugin' | 'unchecked';
+  readonly plugin?: string;
+  readonly required: readonly string[];
+  readonly missing: readonly string[];
+  readonly detail: string;
+  readonly command?: string;
+  readonly fix?: 'install' | 'update';
+  readonly plugins?: readonly PluginStatePayload[];
+  readonly released?: boolean;
+  readonly install?: 'ready' | 'not-declared' | 'env-missing' | 'malformed';
+  readonly libs?: readonly LibStatePayload[];
+}
+
+export interface LibStatePayload {
+  readonly name: string;
+  readonly purpose: string;
+  readonly status: 'ok' | 'outdated' | 'missing' | 'unsatisfied';
+  readonly installed?: string;
+  readonly latest?: string;
+  readonly command?: string;
+}

package/src/components/ApprovalDetail.tsx

@@ -0,0 +1,57 @@
+import type { Translate } from '../api/dsh-client.js';
+import type { ApprovalInput, UnitClientFace } from '../components/board-module.js';
+import { h } from '../lib/react.js';
+
+interface ToolCallRoot {
+  readonly callId?: string;
+  readonly name?: string;
+  readonly phase?: string;
+  readonly argsRaw?: string;
+}
+
+interface ChatSnapshot {
+  readonly nodes?: { values(): Iterable<{ readonly kind?: string; readonly data?: { readonly root?: ToolCallRoot } }> };
+}
+
+type UseChat = <T>(selector: (snapshot: ChatSnapshot) => T) => T | undefined;
+
+export interface ApprovalDetailProps {
+  readonly callId?: string;
+  readonly useChat?: UseChat;
+  readonly units?: readonly UnitClientFace[];
+  readonly t?: Translate;
+}
+
+function callOf(snapshot: ChatSnapshot, callId: string | undefined): { name?: string; argsRaw: string } | undefined {
+  if (callId === undefined) return undefined;
+  for (const node of snapshot.nodes?.values() ?? []) {
+    const root = node.kind === 'tool-call' ? node.data?.root : undefined;
+    if (root?.callId !== callId || root.phase !== 'start') continue;
+    return { ...(root.name === undefined ? {} : { name: root.name }), argsRaw: root.argsRaw ?? '' };
+  }
+  return undefined;
+}
+
+function parseArgs(raw: string): Readonly<Record<string, unknown>> {
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return typeof parsed === 'object' && parsed !== null ? (parsed as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+
+export function ApprovalDetail(props: ApprovalDetailProps) {
+  const useChat = props.useChat ?? ((): undefined => undefined);
+  const call = useChat((snapshot) => callOf(snapshot, props.callId));
+  const t = props.t ?? ((key: string): string => key);
+
+  const args = parseArgs(call?.argsRaw ?? '');
+  const input: ApprovalInput = { tool: call?.name ?? '', args };
+  const command = typeof args.command === 'string' ? args.command : '';
+
+  const owner = (props.units ?? []).find((face) => face.approval?.tools.includes(input.tool) === true);
+  if (owner?.approval !== undefined) return <owner.approval.render input={input} t={t} />;
+
+  return command === '' ? null : <code className="wb-approvalCommand">{command}</code>;
+}

package/src/components/CardHead.tsx

@@ -0,0 +1,74 @@
+import type { ReactNode } from '../lib/react.js';
+import type { Translate } from '../api/dsh-client.js';
+import { IconRefresh, IconRightUp, IconSettings } from '../components/icons.js';
+import { h } from '../lib/react.js';
+
+export interface CardHeadProps {
+  readonly t: Translate;
+  readonly title: string;
+  readonly meta?: ReactNode | undefined;
+  readonly refreshing: boolean;
+  readonly onRefresh: () => void;
+  readonly gear?: string | undefined;
+  readonly gearOpen?: boolean | undefined;
+  readonly onToggleGear?: (() => void) | undefined;
+  readonly platformHref?: string | undefined;
+  readonly platform?: string | undefined;
+  readonly platformTitle?: string | undefined;
+}
+
+export function CardHead({
+  t,
+  title,
+  meta,
+  refreshing,
+  onRefresh,
+  gear,
+  gearOpen,
+  onToggleGear,
+  platformHref,
+  platform,
+  platformTitle,
+}: CardHeadProps) {
+  const refreshLabel = refreshing ? t('rightbar.refreshing') : t('rightbar.refresh');
+  return (
+    <header className="wb-cardHead">
+      <h2 className="wb-cardTitle">{title}</h2>
+      {meta === undefined ? null : <span className="wb-cardMeta">{meta}</span>}
+      {platformHref === undefined || platform === undefined ? null : (
+        <a
+          className="wb-iconButton wb-cardOpen"
+          href={platformHref}
+          target="_blank"
+          rel="noreferrer noopener"
+          title={platformTitle ?? platform}
+          aria-label={platform}
+        >
+          <IconRightUp size={14} />
+        </a>
+      )}
+      <button
+        type="button"
+        className={`wb-iconButton wb-cardRefresh${refreshing ? ' wb-spinning' : ''}`}
+        aria-label={refreshLabel}
+        title={refreshLabel}
+        disabled={refreshing}
+        onClick={onRefresh}
+      >
+        <IconRefresh size={14} />
+      </button>
+      {gear === undefined || onToggleGear === undefined ? null : (
+        <button
+          type="button"
+          className={`wb-iconButton wb-cardGear${gearOpen === true ? ' wb-iconButtonActive' : ''}`}
+          aria-label={gear}
+          aria-expanded={gearOpen === true}
+          title={gear}
+          onClick={onToggleGear}
+        >
+          <IconSettings size={15} />
+        </button>
+      )}
+    </header>
+  );
+}