@dsh-workbench/shared 0.3.4 → 0.3.6

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

@@ -0,0 +1,115 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const HERE = new URL('../', import.meta.url);
+const read = (name: string): string => readFileSync(new URL(name, HERE), 'utf8');
+
+const ROW = read('LongTaskRow.tsx');
+const CSS = read('LongTaskRow.css');
+
+describe('两按停止钮：接线（这仓的组件测试是 node 环境，读源码断言）', () => {
+  it('★★ 不给 stop ⇒ 那颗钮整个不出现；文件里也再没有第二颗 button', () => {
+    const gate = ROW.indexOf('{stop === undefined ? null : (');
+    const button = ROW.indexOf('<button');
+
+    expect(ROW).toContain('const stop = props.stop;');
+    expect(gate).toBeGreaterThan(0);
+    expect(button).toBeGreaterThan(gate);
+    expect(ROW.indexOf('<button', button + 1)).toBe(-1);
+  });
+
+  it('★★ 住在 .wb-longTaskHead 里、最右边那颗（margin-left: auto）', () => {
+    const head = ROW.indexOf('className="wb-longTaskHead"');
+    const button = ROW.indexOf('<button');
+    const close = ROW.indexOf('</p>', button);
+
+    expect(head).toBeGreaterThan(0);
+    expect(button).toBeGreaterThan(head);
+    expect(close).toBeGreaterThan(button);
+    expect(CSS).toContain('margin-left: auto');
+  });
+
+  it('★★ 两按只走 longTaskStopPress(longTaskStopStage({ armed, busy }))：arm 上膛 / fire 落膛并 onStop / ignore 不动', () => {
+    expect(ROW).toContain('longTaskStopPress(longTaskStopStage({ armed, busy }))');
+    expect(ROW).toContain('onClick={onStopPress}');
+    expect(ROW).toContain("if (press === 'ignore') return;");
+    expect(ROW).toContain("if (press === 'arm') {");
+    expect(ROW).toContain('setArmed(true);');
+    expect(ROW).toMatch(/setArmed\(false\);\s*stop\.onStop\(\);/);
+  });
+
+  it('★★ onBlur 落膛（焦点一走就退回没上膛）', () => {
+    expect(ROW).toContain('onBlur={() => setArmed(false)}');
+  });
+
+  it('★★ 上膛后 3 秒自己落膛：用 LONG_TASK_STOP_ARM_MS，卸载 / 落膛都清掉计时器', () => {
+    expect(ROW).toContain("from '../api/long-task.js'");
+    expect(ROW).toContain('setTimeout(() => setArmed(false), LONG_TASK_STOP_ARM_MS)');
+    expect(ROW).toContain('clearTimeout(timer)');
+    expect(ROW).toContain('}, [armed]);');
+  });
+
+  it('★★ data-stop-state 交出那一档（照 dsh 的 data-kill-state）', () => {
+    expect(ROW).toContain('data-stop-state={longTaskStopStage({ armed, busy })}');
+  });
+
+  it('★★ busy 时 disabled；上膛时多一个 span 显示 askLabel；三句词全部由调用点给', () => {
+    expect(ROW).toContain('const busy = stop?.busy === true;');
+    expect(ROW).toContain('disabled={busy}');
+    expect(ROW).toContain('<span className="wb-longTaskStopLabel">{stop.askLabel}</span>');
+    expect(ROW).toContain('aria-label={armed ? stop.armedLabel ?? stop.askLabel : stop.label}');
+    expect(ROW).toContain('<IconStopFillRegular size={12} />');
+    expect(ROW).toContain('type="button"');
+    expect(ROW).not.toContain('Translate');
+  });
+
+  it('★★ failed 非空 ⇒ 在 problem 那行后面再画一行（wb-longTaskStopWhy）', () => {
+    const problem = ROW.indexOf('className="wb-longTaskProblem"');
+    const why = ROW.indexOf('className="wb-longTaskStopWhy"');
+
+    expect(ROW).toContain("const stopWhy = stop?.failed ?? '';");
+    expect(ROW).toContain('className="wb-longTaskStopWhy">{stopWhy}');
+    expect(problem).toBeGreaterThan(0);
+    expect(why).toBeGreaterThan(problem);
+  });
+
+  it('★★ 没有 stop 的行一个像素都不变：既要的规则一个字没动，新规则也只在带钮的行上起作用', () => {
+    expect(CSS).toContain('.wb-longTaskHeadline {\n  margin: 0;');
+    expect(CSS).toContain('.wb-longTaskLink {\n  flex: none;\n}');
+    expect(CSS).toContain('.wb-longTaskHead {');
+  });
+});
+
+describe('两按停止钮：样式跟 dsh 那颗钮同款（组件自带，同目录一份 .css）', () => {
+  it('★★ 四个类都在同目录那份 .css 里', () => {
+    for (const cls of [
+      '.wb-longTaskStop {',
+      '.wb-longTaskStopArmed,',
+      '.wb-longTaskStopLabel {',
+      '.wb-longTaskStopWhy {',
+    ]) {
+      expect(CSS).toContain(cls);
+    }
+  });
+
+  it('★★ 上膛变宽（width: auto），取值照 dsh：error 45% 边框 + 12% 底 + gap 4 + padding 0 7px', () => {
+    expect(CSS).toMatch(/\.wb-longTaskStopArmed[\s\S]*width: auto/);
+    expect(CSS).toContain('color-mix(in srgb, var(--dsw-alias-state-error-primary) 45%, transparent)');
+    expect(CSS).toContain('color-mix(in srgb, var(--dsw-alias-state-error-primary) 12%, transparent)');
+    expect(CSS).toContain('gap: var(--wb-len-4)');
+    expect(CSS).toContain('padding: 0 var(--wb-len-7)');
+  });
+
+  it('★★ 上膛那颗字 11px / 18px；失败那行 error 色', () => {
+    expect(CSS).toContain('font-size: var(--dsw-font-xxxs-11-font-size)');
+    expect(CSS).toContain('line-height: var(--wb-line-18)');
+    expect(CSS).toMatch(/\.wb-longTaskStopWhy \{[\s\S]*--dsw-alias-state-error-primary/);
+  });
+
+  it('★ 一格注释都没有，颜色不写字面值（尺寸走 --wb-len-*）', () => {
+    expect(CSS).not.toContain('/*');
+    expect(CSS).not.toContain('#');
+    expect(CSS).toContain('var(--wb-len-20)');
+    expect(CSS).not.toMatch(/(^|[^a-z-])rgb\(/);
+  });
+});

package/src/components/board-module.ts

@@ -4,10 +4,16 @@ import type { UnitManifest } from '../api/unit.js';
 import type { CapabilityPayload } from '../api/workbench-contract.js';
 import type { Dictionaries } from '../i18n/index.js';
 
+/**
+ * 面板要跳去的一格：只用 `kind` 说去哪，具体负载由各 unit 自己约定。
+ */
 export interface PanelStep {
   readonly kind: string;
 }
 
+/**
+ * 交给面板渲染的宿主世界：工作区与会话快照、装着的 unit、面板开关、能力表与当前选中。
+ */
 export interface SuiteWorld {
   readonly workspaces: WorkspaceSnapshot;
   readonly sessions: SessionsSnapshot;
@@ -20,6 +26,9 @@ export interface SuiteWorld {
   };
 }
 
+/**
+ * 面板视图的统一 prop：一份世界快照 + 刷新令牌 + 四个通知回调 + 翻译函数。
+ */
 export interface BoardModuleProps {
   readonly world: SuiteWorld;
   readonly refreshToken: number;
@@ -30,16 +39,25 @@ export interface BoardModuleProps {
   readonly t: Translate;
 }
 
+/**
+ * 一张卡报给宿主的摘要：此刻在不在刷新、上次读到是哪个时刻。
+ */
 export interface ModuleSummary {
   readonly refreshing: boolean;
   readonly at: number | null;
 }
 
+/**
+ * unit 的一个子步骤：标题文案键 + 渲染这件视图的组件。
+ */
 export interface UnitStep {
   readonly titleKey: string;
   readonly View: (props: BoardModuleProps) => ReactNode;
 }
 
+/**
+ * 一个面板单元的注册面：id、标题键、排序、视图，可带一组子步骤。
+ */
 export interface BoardModule {
   readonly id: string;
   readonly titleKey: string;
@@ -48,6 +66,9 @@ export interface BoardModule {
   readonly steps?: Readonly<Record<string, UnitStep>>;
 }
 
+/**
+ * 模块在浏览器侧交出来的那份面：卡片、子步骤、自己的字典，以及审批渲染。
+ */
 export interface UnitClientFace {
   readonly unit: string;
   readonly card?: (props: BoardModuleProps) => ReactNode;
@@ -61,15 +82,24 @@ export interface UnitClientFace {
     | undefined;
 }
 
+/**
+ * 带着自己 manifest 的模块面（外壳按 unit 认领时用）。
+ */
 export interface UnitOwnedClientFace extends UnitClientFace {
   readonly manifest: UnitManifest;
 }
 
+/**
+ * 一次审批要看的输入：工具名，与它这次收到的参数。
+ */
 export interface ApprovalInput {
   readonly tool: string;
   readonly args: Readonly<Record<string, unknown>>;
 }
 
+/**
+ * 模块注册进外壳的那个口：注册一份面（拿回注销函数）、列出已装 unit。
+ */
 export interface UnitClientApi {
   registerUnit(face: UnitClientFace): () => void;
   manifests(): readonly UnitManifest[];

package/src/components/icons.tsx

@@ -1,5 +1,8 @@
 import { h, type ReactNode } from '../lib/react.js';
 
+/**
+ * 自绘图标的契约：只给边长像素。
+ */
 export interface IconProps {
   size?: number;
 }
@@ -31,6 +34,11 @@ function Shell({
   );
 }
 
+/**
+ * 会话图标：一枚对话气泡，dsh 的图标表里没有，留给我们自己用；默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export function IconConversation({ size = 16 }: IconProps) {
   return (
     <Shell size={size} strokeWidth={1.3}>
@@ -43,6 +51,11 @@ export function IconConversation({ size = 16 }: IconProps) {
   );
 }
 
+/**
+ * 品牌标：侧栏顶上那枚工作台方块标；默认 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">
@@ -56,6 +69,11 @@ export function IconBrandMark({ size = 24 }: IconProps) {
   );
 }
 
+/**
+ * opencli 的标：包类型那一格用它；颜色写死的品牌物，不跟主题走。默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export function IconOpencli({ size = 16 }: IconProps) {
   return (
     <Shell size={size} viewBox="0 0 64 64">
@@ -83,6 +101,11 @@ export function IconOpencli({ size = 16 }: IconProps) {
   );
 }
 
+/**
+ * npm 的标：包类型那一格用它；保留品牌红，不跟主题走。默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export function IconNpm({ size = 16 }: IconProps) {
   return (
     <Shell size={size} viewBox="0 0 1024 1024">
@@ -94,6 +117,11 @@ 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">
@@ -105,6 +133,11 @@ export function IconModules({ size = 16 }: IconProps) {
   );
 }
 
+/**
+ * 模块类型标：渐变方块 + 白四宫格，用在"这是个模块"的行首；品牌物，颜色不跟主题走。默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export function IconModuleMark({ size = 16 }: IconProps) {
   return (
     <Shell size={size} viewBox="0 0 24 24">
@@ -124,6 +157,11 @@ export function IconModuleMark({ size = 16 }: IconProps) {
   );
 }
 
+/**
+ * 面板 / 卡片那类的图标：整屏与柱状那种形状，给"面板"这一档用；默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export function IconPanelScreen({ size = 16 }: IconProps) {
   return (
     <svg

package/src/config/constants.ts

@@ -1,79 +1,122 @@
+/** 外壳插件的包名：浏览器模块表与宿主按它注册、认领这枚插件。 */
 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";
 
+/** 模块偏好读写的路由前缀，挂在外壳 API 下：走写通道，拒写回 write-refused。 */
 export const PREFS_PREFIX = `${API_PREFIX}/prefs`;
 
+/** 事实（facts）SSE 事件流的端点路径；前端 `EventSource` 按它带 `since` 游标续传。 */
 export const EVENTS_PATH = "/workbench/events";
+/** 写动作的路由前缀，挂在外壳 API 下：模块的写通道 POST 到这里。 */
 export const ACTIONS_PREFIX = `${API_PREFIX}/actions`;
 
+/** 机器供给（provision）的路由前缀：只收 POST，装机时用它铺一份运行环境。 */
 export const PROVISION_PREFIX = `${API_PREFIX}/provision`;
 
+/** 面板运行态上报的路径段：崩溃与卡片收尾分别 POST 到 `panel-state/crash`、`panel-state/cards`。 */
 export const PANEL_STATE_PATH = "panel-state";
 
+/** DIY 调试动作的路径段；宿主按它登记 `/workbench/api/diy-debug` 前缀。 */
 export const DIY_DEBUG_PATH = "diy-debug";
+/** 调试动作的子路径（`diy-debug/act`）；仓内暂无调用点，动作现走 `DIY_DEBUG_SERVICE`。 */
 export const DIY_DEBUG_ACT_PATH = `${DIY_DEBUG_PATH}/act`;
 
+/** DIY 录制交接的路径段；宿主按它登记 `/workbench/api/diy-record` 前缀。 */
 export const DIY_RECORD_PATH = "diy-record";
+/** 录制动作的子路径（`diy-record/act`）；仓内暂无调用点，录制现走 `DIY_RECORD_SERVICE`。 */
 export const DIY_RECORD_ACT_PATH = `${DIY_RECORD_PATH}/act`;
 
+/** 面板运行态的路由前缀，挂在外壳 API 下：上报口用它，拒报回 report-refused。 */
 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 服务名（`workbenchPanels`）：宿主经它取套件公布的清单与订阅。 */
 export const PANELS_SERVICE = "workbenchPanels";
 
+/** 单元花名册服务的 dsh 服务名（`workbenchUnits`）：模块经它认领自己的单元。 */
 export const UNITS_SERVICE = "workbenchUnits";
 
+/** 面板运行态服务的 dsh 服务名（`workbenchPanelState`）：宿主注册，读口按它取。 */
 export const PANEL_STATE_SERVICE = "workbenchPanelState";
 
+/** DIY 调试约定服务的 dsh 服务名（`workbenchDiyDebug`）：调试动作走它，不走 HTTP。 */
 export const DIY_DEBUG_SERVICE = "workbenchDiyDebug";
 
+/** DIY 录制交接服务的 dsh 服务名（`workbenchDiyRecord`）：`diy-acts.ts` 经它收发录制三拍。 */
 export const DIY_RECORD_SERVICE = "workbenchDiyRecord";
 
+/** 会话投影服务的 dsh 服务名（`sessionProjections`）：宿主经 `stateOf(session, 'agentPreset')` 读那一档。 */
+export const SESSION_PROJECTIONS_SERVICE = "sessionProjections";
+
+/** 面板清单一次取回的行数上限（条）：外部模块拿它当 opencli `--pageSize`。 */
 export const PANEL_LIST_LIMIT = 50;
 
+/** 单次 opencli 调用的默认超时（毫秒）；调用点没传 `timeoutMs` 时按它算。 */
 export const OPENCLI_TIMEOUT_MS = 120_000;
 
+/** 同时最多几条 opencli 在跑（条）：`opencli.ts` 超出就排队。 */
 export const OPENCLI_MAX_CONCURRENT = 4;
 
+/** 启动预热站点那一跳的超时（毫秒）；超时按未热对待，不挡面板。 */
 export const WARM_TIMEOUT_MS = 20_000;
 
+/** 装 / 卸模块包的超时（毫秒）：pnpm 与取包内容都按它算。 */
 export const INSTALL_TIMEOUT_MS = 300_000;
 
+/** 查 registry 版本那一次请求的超时（毫秒）。 */
 export const VERSION_CHECK_TIMEOUT_MS = 10_000;
 
+/** 版本查询结果的缓存有效期（毫秒）：期内不发第二次请求。 */
 export const VERSION_CHECK_TTL_MS = 600_000;
 
+/** 单元探测结果的缓存有效期（毫秒）。 */
 export const PROBE_TTL_MS = 30_000;
 
+/** 加载态至少显示多久（毫秒）：一瞬完成的读写也得让用户看见那一下。 */
 export const MIN_BUSY_MS = 500;
 
+/** 工具读出来的值交给面板后的保留时长（毫秒）：过期就不再算这一拍。 */
 export const HANDOFF_TTL_MS = 15_000;
 
+/** 跑本地 git 命令的超时（毫秒）；短于对外的 `OPENCLI_TIMEOUT_MS`。 */
 export const GIT_TIMEOUT_MS = 10_000;
 
+/** 面板轮询事实的间隔（毫秒）：SSE 断了走这条兜底轮询。 */
 export const PANEL_POLL_MS = 2000;
 
+/** 没起中文名的工作区默认标题：左栏按它分组、显示。 */
 export const DEFAULT_WORKSPACE_TITLE = "default-workspace";
 
+/** 记住当前项目的 localStorage 键。 */
 export const STORAGE_KEY_PROJECT = "dsh-workbench.project";
 
+/** 记住右栏展开与否的 localStorage 键。 */
 export const STORAGE_KEY_RIGHTBAR = "dsh-workbench.rightbar.expanded";
 
+/** 记住右栏当前列的 localStorage 键。 */
 export const STORAGE_KEY_RIGHTBAR_COLUMN = "dsh-workbench.rightbar.column";
 
+/** 记住右栏宽度（像素数字的字符串）的 localStorage 键。 */
 export const STORAGE_KEY_RIGHTBAR_WIDTH = "dsh-workbench.rightbar.width";
 
+/** 右栏宽度达到或超过多少像素就按全屏对待（阈值，像素）。 */
 export const RIGHTBAR_FULLSCREEN_WIDTH = 768;
 
+/** dsh i18n 的命名空间：词表都注册在它下面，`ctx.locale.register` / `bind` 按它取。 */
 export const LOCALE_NS = "workbench";
 
+/** 外壳支持的语言标识，顺序即回退顺序：首项是基准，其余词表必须与它逐键同构。 */
 export const LOCALES = ["zh", "en"] as const;

package/src/config/storage.ts

@@ -1,3 +1,4 @@
+/** 读 localStorage 里的一段文本；没有这个键、或存储不可用（隐私模式）时返回 null。 */
 export function readText(key: string): string | null {
   try {
     return window.localStorage.getItem(key);
@@ -6,6 +7,7 @@ export function readText(key: string): string | null {
   }
 }
 
+/** 写一段文本进 localStorage；`value` 为 null 时删掉这个键，写不进去就静默作罢。 */
 export function writeText(key: string, value: string | null): void {
   try {
     if (value === null) window.localStorage.removeItem(key);
@@ -14,12 +16,14 @@ export function writeText(key: string, value: string | null): void {
   }
 }
 
+/** 读一个布尔开关：键不存在时返回 `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');
 }