@dsh-workbench/shared 0.2.13 → 0.2.15

package/dist/index.d.ts

@@ -20,6 +20,7 @@ export * from './components/CardBoundary.js';
 export * from './components/CardHead.js';
 export * from './components/ChoiceGroup.js';
 export * from './components/Field.js';
+export * from './components/FormActions.js';
 export * from './components/FormRows.js';
 export * from './components/Link.js';
 export * from './components/LongTaskRow.js';
@@ -44,6 +45,7 @@ export * from './i18n/zh.js';
 export * from './lib/blocker-action.js';
 export * from './lib/busy.js';
 export * from './lib/form-problem.js';
+export * from './lib/diy-debug.js';
 export * from './lib/panel-state.js';
 export * from './lib/react.js';
 export * from './lib/text.js';

package/dist/index.js

@@ -20,6 +20,7 @@ export * from './components/CardBoundary.js';
 export * from './components/CardHead.js';
 export * from './components/ChoiceGroup.js';
 export * from './components/Field.js';
+export * from './components/FormActions.js';
 export * from './components/FormRows.js';
 export * from './components/Link.js';
 export * from './components/LongTaskRow.js';
@@ -44,6 +45,7 @@ export * from './i18n/zh.js';
 export * from './lib/blocker-action.js';
 export * from './lib/busy.js';
 export * from './lib/form-problem.js';
+export * from './lib/diy-debug.js';
 export * from './lib/panel-state.js';
 export * from './lib/react.js';
 export * from './lib/text.js';

package/dist/lib/diy-debug.d.ts

@@ -0,0 +1,38 @@
+export type DebugPhase = 'debugging' | 'paused';
+export declare const DEBUG_STALE_MS: number;
+export interface DebugState {
+    readonly phase: DebugPhase;
+    readonly sessionId: string;
+    readonly workspace: string;
+    readonly board: string;
+    readonly unit: string;
+    readonly name: string;
+    readonly startedAt: number;
+    readonly at: number;
+}
+export interface DebugPact {
+    readonly sessionId: string;
+    readonly workspace: string;
+    readonly board: string;
+    readonly unit: string;
+    readonly name: string;
+    readonly now: number;
+}
+export type DebugRefusal = 'already-held' | 'held-by-other' | 'not-owner' | 'none' | 'already-paused' | 'already-debugging';
+export type DebugMove = {
+    readonly ok: true;
+    readonly state: DebugState;
+} | {
+    readonly ok: false;
+    readonly code: DebugRefusal;
+};
+export interface DebugStore {
+    live(now: number): DebugState | null;
+    begin(pact: DebugPact): DebugMove;
+    stall(sessionId: string, now: number): DebugMove;
+    pause(sessionId: string, now: number): DebugMove;
+    resume(sessionId: string, now: number): DebugMove;
+    stop(sessionId: string, now: number): DebugMove;
+}
+export declare function createDebugStore(): DebugStore;
+export declare function debugOwnerText(state: DebugState): string;

package/dist/lib/diy-debug.js

@@ -0,0 +1,77 @@
+export const DEBUG_STALE_MS = 4 * 60 * 60 * 1000;
+function alive(state, now) {
+    if (state === null)
+        return null;
+    return now - state.at <= DEBUG_STALE_MS ? state : null;
+}
+function ownerOf(state, sessionId, now) {
+    const held = alive(state, now);
+    if (held === null)
+        return 'none';
+    return held.sessionId === sessionId ? held : 'not-owner';
+}
+export function createDebugStore() {
+    let held = null;
+    const live = (now) => alive(held, now);
+    return {
+        live,
+        begin(pact) {
+            const current = alive(held, pact.now);
+            if (current !== null) {
+                return { ok: false, code: current.sessionId === pact.sessionId ? 'already-held' : 'held-by-other' };
+            }
+            const state = {
+                phase: 'debugging',
+                sessionId: pact.sessionId,
+                workspace: pact.workspace,
+                board: pact.board,
+                unit: pact.unit,
+                name: pact.name,
+                startedAt: pact.now,
+                at: pact.now,
+            };
+            held = state;
+            return { ok: true, state };
+        },
+        stall(sessionId, now) {
+            const found = ownerOf(held, sessionId, now);
+            if (typeof found === 'string')
+                return { ok: false, code: found };
+            if (found.phase === 'paused')
+                return { ok: false, code: 'already-paused' };
+            const state = { ...found, phase: 'paused', at: now };
+            held = state;
+            return { ok: true, state };
+        },
+        pause(sessionId, now) {
+            const found = ownerOf(held, sessionId, now);
+            if (typeof found === 'string')
+                return { ok: false, code: found };
+            if (found.phase === 'paused')
+                return { ok: false, code: 'already-paused' };
+            const state = { ...found, phase: 'paused', at: now };
+            held = state;
+            return { ok: true, state };
+        },
+        resume(sessionId, now) {
+            const found = ownerOf(held, sessionId, now);
+            if (typeof found === 'string')
+                return { ok: false, code: found };
+            if (found.phase === 'debugging')
+                return { ok: false, code: 'already-debugging' };
+            const state = { ...found, phase: 'debugging', at: now };
+            held = state;
+            return { ok: true, state };
+        },
+        stop(sessionId, now) {
+            const found = ownerOf(held, sessionId, now);
+            if (typeof found === 'string')
+                return { ok: false, code: found };
+            held = null;
+            return { ok: true, state: found };
+        },
+    };
+}
+export function debugOwnerText(state) {
+    return `会话 ${state.sessionId}（自 ${new Date(state.startedAt).toISOString().slice(11, 19)}Z 起在调试 ${state.unit}）`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-workbench/shared",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "工作台与模块共享的纯代码与契约类型：类型、纯逻辑、哑组件、平台解析。宿主侧的东西从 /host 进（不影响浏览器产物）。",
   "license": "MIT",
   "type": "module",

package/src/api/dsh.ts

@@ -151,7 +151,12 @@ export interface DshToolDefinition {
 export interface DshToolRunContext {
   readonly agent?:
     | {
-        readonly session?: { readonly header?: { readonly cwd?: string } | undefined } | undefined;
+        readonly session?:
+          | {
+              readonly id?: string;
+              readonly header?: { readonly cwd?: string } | undefined;
+            }
+          | undefined;
       }
     | undefined;
 }

package/src/components/FormActions.css

@@ -0,0 +1,13 @@
+.wb-formActions {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: flex-end;
+  gap: var(--wb-len-8);
+}
+
+.wb-formActionDanger {
+  color: var(--dsw-alias-state-error-primary);
+  border-color: color-mix(in srgb, var(--dsw-alias-state-error-primary) 30%, transparent);
+  --dsw-alias-interactive-bg-hover: color-mix(in srgb, var(--dsw-alias-state-error-primary) 8%, transparent);
+}

package/src/components/FormActions.test.tsx

@@ -0,0 +1,157 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it, vi } from 'vitest';
+import { FormActions, type FormAction, type FormActionKind } from './FormActions.js';
+import { SaveBar } from './SaveBar.js';
+
+function action(key: string, kind?: FormActionKind): FormAction {
+  return { key, label: key, ...(kind === undefined ? {} : { kind }), onClick: () => {} };
+}
+
+function buttonsOf(node: unknown): { props: Record<string, unknown> }[] {
+  return (node as { props: { children: unknown[] } }).props.children as { props: Record<string, unknown> }[];
+}
+
+function labelsOf(node: unknown): unknown[] {
+  return buttonsOf(node).map((one) => one.props['children']);
+}
+
+describe('FormActions', () => {
+  it('★ 顺序由组件决定：给乱序数组，primary 仍在末尾、danger 紧挨它左侧、其余保持调用点顺序', () => {
+    const node = FormActions({
+      actions: [action('save', 'primary'), action('retry'), action('remove', 'danger'), action('edit')],
+    });
+
+    expect(labelsOf(node)).toEqual(['retry', 'edit', 'remove', 'save']);
+    expect(buttonsOf(node).map((one) => one.props['variant'])).toEqual([
+      'ghost',
+      'ghost',
+      'outline',
+      'primary',
+    ]);
+  });
+
+  it('没有 primary 时 danger 仍是最后一个（固定槽位，不随调用点顺序漂）', () => {
+    const node = FormActions({ actions: [action('remove', 'danger'), action('reset')] });
+
+    expect(labelsOf(node)).toEqual(['reset', 'remove']);
+  });
+
+  it('★ 两颗 primary 给可诊断信号（点名 key），但不吞、不挪、不丢', () => {
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    try {
+      const node = FormActions({ actions: [action('keep', 'primary'), action('also', 'primary')] });
+
+      expect(spy).toHaveBeenCalledTimes(1);
+      const message = String(spy.mock.calls[0]?.[0]);
+      expect(message).toContain('[dsh-workbench]');
+      expect(message).toContain('keep');
+      expect(message).toContain('also');
+      expect(labelsOf(node)).toEqual(['keep', 'also']);
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
+  it('一颗 primary 不报', () => {
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    try {
+      FormActions({ actions: [action('save', 'primary'), action('cancel')] });
+      expect(spy).not.toHaveBeenCalled();
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
+  it('★ 空数组不渲空壳', () => {
+    expect(FormActions({ actions: [] })).toBeNull();
+  });
+
+  it('danger 是 outline + 危险类，绝不是 primary 填充', () => {
+    const node = FormActions({ actions: [action('remove', 'danger')] });
+    const only = buttonsOf(node)[0];
+
+    expect(only?.props['variant']).toBe('outline');
+    expect(only?.props['className']).toBe('wb-formActionDanger');
+  });
+
+  it('busy 那颗禁用并带 Spinner；disabled 单独算', () => {
+    const node = FormActions({
+      actions: [
+        { key: 'save', label: '保存', kind: 'primary', onClick: () => {}, busy: true },
+        { key: 'cancel', label: '取消', onClick: () => {}, disabled: true },
+      ],
+    });
+    const [cancel, save] = buttonsOf(node);
+
+    expect(save?.props['disabled']).toBe(true);
+    expect(save?.props['icon']).toBeTruthy();
+    expect(cancel?.props['disabled']).toBe(true);
+    expect(cancel?.props['icon']).toBeUndefined();
+  });
+});
+
+const CSS = readFileSync(new URL('./FormActions.css', import.meta.url), 'utf8');
+
+function declarations(selector: string): string[] {
+  for (const block of CSS.split('}')) {
+    const [head, ...rest] = block.split('{');
+    if (rest.length === 0 || head === undefined) continue;
+    if (head.trim() !== selector) continue;
+    return rest
+      .join('{')
+      .split(';')
+      .map((one) => one.replace(/\s+/g, ' ').trim())
+      .filter((one) => one !== '');
+  }
+  throw new Error(`FormActions.css 里没有这条规则：${selector}`);
+}
+
+describe('操作区的版式（ADR-0054 §2 规则四）', () => {
+  it('★ 窄容器换行 + 整组右对齐 + 唯一一档间距', () => {
+    const rule = declarations('.wb-formActions');
+
+    expect(rule).toContain('flex-wrap: wrap');
+    expect(rule).toContain('justify-content: flex-end');
+    expect(rule).toContain('gap: var(--wb-len-8)');
+  });
+
+  it('★ 危险色走现成令牌（文字 / 描边 / 悬停）', () => {
+    const rule = declarations('.wb-formActionDanger');
+
+    expect(rule).toContain('color: var(--dsw-alias-state-error-primary)');
+    expect(rule.some((one) => one.startsWith('border-color: color-mix(in srgb, var(--dsw-alias-state-error-primary)'))).toBe(
+      true,
+    );
+    expect(rule.some((one) => one.startsWith('--dsw-alias-interactive-bg-hover:'))).toBe(true);
+  });
+});
+
+describe('SaveBar 自吃狗粮（ADR-0054 §10）', () => {
+  it('两个动作喂给 FormActions：取消是 default、保存是 primary（顺序不再由它摆）', () => {
+    const node = SaveBar({
+      busy: false,
+      labels: { cancel: '取消', save: '保存', saving: '保存中…' },
+      onCancel: () => {},
+      onSave: () => {},
+    }) as unknown as { props: { actions: readonly FormAction[] } };
+
+    expect(node.props.actions.map((one) => [one.key, one.kind])).toEqual([
+      ['cancel', 'default'],
+      ['save', 'primary'],
+    ]);
+  });
+
+  it('busy 时保存那颗显示 saving 文案、禁用且带忙碌标记', () => {
+    const node = SaveBar({
+      busy: true,
+      labels: { cancel: '取消', save: '保存', saving: '保存中…' },
+      onCancel: () => {},
+      onSave: () => {},
+    }) as unknown as { props: { actions: readonly FormAction[] } };
+    const save = node.props.actions[1];
+
+    expect(save?.label).toBe('保存中…');
+    expect(save?.disabled).toBe(true);
+    expect(save?.busy).toBe(true);
+  });
+});

package/src/components/FormActions.tsx

@@ -0,0 +1,75 @@
+import type { ReactNode } from '../lib/react.js';
+import { h } from '../lib/react.js';
+import { Button } from '@deepseek-ai/dsh-client-ui-primitives';
+import { Spinner } from './Spinner.js';
+import './FormActions.css';
+
+export type FormActionKind = 'default' | 'danger' | 'primary';
+
+export interface FormAction {
+  readonly key: string;
+  readonly label: ReactNode;
+  readonly kind?: FormActionKind | undefined;
+  readonly onClick: () => void;
+  readonly disabled?: boolean | undefined;
+  readonly busy?: boolean | undefined;
+}
+
+export interface FormActionsProps {
+  readonly actions: readonly FormAction[];
+}
+
+const RANK: Record<FormActionKind, number> = { default: 0, danger: 1, primary: 2 };
+
+function kindOf(action: FormAction): FormActionKind {
+  return action.kind ?? 'default';
+}
+
+function ordered(actions: readonly FormAction[]): readonly FormAction[] {
+  return actions
+    .map((action, index) => ({ action, index, rank: RANK[kindOf(action)] }))
+    .sort((left, right) => left.rank - right.rank || left.index - right.index)
+    .map((one) => one.action);
+}
+
+function reportExtraPrimaries(actions: readonly FormAction[]): void {
+  const keys = actions.filter((one) => kindOf(one) === 'primary').map((one) => one.key);
+  if (keys.length < 2) return;
+  console.error(
+    `[dsh-workbench] FormActions 一个区里出现了 ${keys.length} 颗 primary（${keys.join('、')}）—— ` +
+      '一个区只许一颗主操作（ADR-0054 §2 规则二）：多余的这颗该改成 default',
+  );
+}
+
+function variantOf(kind: FormActionKind): 'ghost' | 'outline' | 'primary' {
+  if (kind === 'primary') return 'primary';
+  if (kind === 'danger') return 'outline';
+  return 'ghost';
+}
+
+export function FormActions({ actions }: FormActionsProps) {
+  if (actions.length === 0) return null;
+  reportExtraPrimaries(actions);
+  return (
+    <div className="wb-formActions">
+      {ordered(actions).map((action) => {
+        const kind = kindOf(action);
+        const busy = action.busy === true;
+        return (
+          <Button
+            key={action.key}
+            type="button"
+            size="sm"
+            variant={variantOf(kind)}
+            className={kind === 'danger' ? 'wb-formActionDanger' : undefined}
+            disabled={busy || action.disabled === true}
+            icon={busy ? <Spinner size={12} /> : undefined}
+            onClick={action.onClick}
+          >
+            {action.label}
+          </Button>
+        );
+      })}
+    </div>
+  );
+}

package/src/components/FormRows.css

@@ -1,14 +1,25 @@
 .wb-formRows {
-  display: flex;
-  flex-direction: column;
-  gap: var(--wb-len-12);
+  display: grid;
+  grid-template-columns: minmax(72px, max-content) minmax(0, 1fr);
+  column-gap: var(--wb-len-8);
+  row-gap: var(--wb-len-12);
+}
+
+.wb-formRows > :not(.wb-formRow) {
+  grid-column: 1 / -1;
 }
 
 .wb-formRow {
   display: grid;
-  grid-template-columns: 72px minmax(0, 1fr);
+  grid-column: 1 / -1;
+  grid-template-columns: minmax(72px, max-content) minmax(0, 1fr);
   align-items: center;
-  gap: var(--wb-len-8);
+  column-gap: var(--wb-len-8);
+  row-gap: var(--wb-len-8);
+}
+
+.wb-formRows > .wb-formRow {
+  grid-template-columns: subgrid;
 }
 
 .wb-formRow[data-layout='stacked'] {
@@ -22,6 +33,11 @@
   font-size: var(--dsw-font-xs-13-font-size);
   color: var(--dsw-alias-label-secondary);
   overflow-wrap: anywhere;
+  white-space: nowrap;
+}
+
+.wb-formRow[data-layout='stacked'] .wb-formLabel {
+  white-space: normal;
 }
 
 .wb-formControl {

package/src/components/FormRows.test.tsx

@@ -1,3 +1,4 @@
+import { readFileSync } from 'node:fs';
 import { describe, expect, it } from 'vitest';
 import { FormRow, FormRows } from './FormRows.js';
 
@@ -80,3 +81,58 @@ describe('FormRow', () => {
     expect(texts(node)).toEqual(['两行']);
   });
 });
+
+const FORM_CSS = readFileSync(new URL('./FormRows.css', import.meta.url), 'utf8');
+
+function declarations(selector: string): string[] {
+  for (const block of FORM_CSS.split('}')) {
+    const [head, ...rest] = block.split('{');
+    if (rest.length === 0 || head === undefined) continue;
+    if (head.trim() !== selector) continue;
+    return rest
+      .join('{')
+      .split(';')
+      .map((one) => one.replace(/\s+/g, ' ').trim())
+      .filter((one) => one !== '');
+  }
+  throw new Error(`FormRows.css 里没有这条规则：${selector}`);
+}
+
+describe('标签列：同一个 FormRows 共用一列（ADR-0052 §11）', () => {
+  it('★ FormRows 自己是一个 grid：标签列 minmax(72px, max-content)，行距还是那一档', () => {
+    const rows = declarations('.wb-formRows');
+
+    expect(rows).toContain('display: grid');
+    expect(rows).toContain('grid-template-columns: minmax(72px, max-content) minmax(0, 1fr)');
+    expect(rows).toContain('row-gap: var(--wb-len-12)');
+  });
+
+  it('★ 行先留回退两列，再由 subgrid 继承父网格那两列（老浏览器丢掉 subgrid 仍有回退）', () => {
+    expect(declarations('.wb-formRow')).toContain(
+      'grid-template-columns: minmax(72px, max-content) minmax(0, 1fr)',
+    );
+    expect(declarations('.wb-formRows > .wb-formRow')).toContain('grid-template-columns: subgrid');
+  });
+
+  it('★ 行自己的列距与 FormRows 那一档同值（不同值就是控件起点参差）', () => {
+    const rowGap = declarations('.wb-formRow').find((one) => one.startsWith('column-gap:'));
+    const rowsGap = declarations('.wb-formRows').find((one) => one.startsWith('column-gap:'));
+
+    expect(rowGap).toBe('column-gap: var(--wb-len-8)');
+    expect(rowGap).toBe(rowsGap);
+  });
+
+  it('★ 标签不折行；stacked 还是单列、标签照常换行', () => {
+    expect(declarations('.wb-formLabel')).toContain('white-space: nowrap');
+    expect(declarations(".wb-formRow[data-layout='stacked'] .wb-formLabel")).toContain(
+      'white-space: normal',
+    );
+    expect(declarations(".wb-formRow[data-layout='stacked']")).toContain(
+      'grid-template-columns: minmax(0, 1fr)',
+    );
+  });
+
+  it('★ 不是 FormRow 的子项（分组标题那种）通栏，别被塞进标签那一列', () => {
+    expect(declarations('.wb-formRows > :not(.wb-formRow)')).toContain('grid-column: 1 / -1');
+  });
+});

package/src/components/SaveBar.tsx

@@ -1,6 +1,6 @@
-import { Button } from '@deepseek-ai/dsh-client-ui-primitives';
 import { h } from '../lib/react.js';
-import './SaveBar.css';
+import type { FormAction } from './FormActions.js';
+import { FormActions } from './FormActions.js';
 
 export interface SaveBarProps {
   readonly busy: boolean;
@@ -15,20 +15,16 @@ export interface SaveBarProps {
 }
 
 export function SaveBar({ busy, disabled, labels, onCancel, onSave }: SaveBarProps) {
-  return (
-    <div className="wb-formActions">
-      <Button type="button" size="sm" variant="ghost" onClick={onCancel} disabled={busy}>
-        {labels.cancel}
-      </Button>
-      <Button
-        type="button"
-        size="sm"
-        variant="primary"
-        onClick={onSave}
-        disabled={busy || disabled === true}
-      >
-        {busy ? labels.saving : labels.save}
-      </Button>
-    </div>
-  );
+  const actions: readonly FormAction[] = [
+    { key: 'cancel', label: labels.cancel, kind: 'default', onClick: onCancel, disabled: busy },
+    {
+      key: 'save',
+      label: busy ? labels.saving : labels.save,
+      kind: 'primary',
+      onClick: onSave,
+      disabled: busy || disabled === true,
+      busy,
+    },
+  ];
+  return <FormActions actions={actions} />;
 }

package/src/components/SelectField.css

@@ -61,6 +61,26 @@
   box-shadow: none;
 }
 
+.wb-selectIconOnly {
+  width: var(--wb-len-36);
+  height: var(--wb-len-36);
+  min-height: 0;
+  gap: 0;
+  padding: 0;
+  justify-content: center;
+}
+
+.wb-selectReveal {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.wb-selectIconOnly .wb-selectIcon {
+  width: 100%;
+  height: 100%;
+}
+
 .wb-selectAnchor {
   display: block;
   width: 100%;