@dsh-workbench/shared 0.3.3 → 0.3.5

package/src/lib/diy-record.ts

@@ -0,0 +1,185 @@
+/**
+ * 录制交接的三个相位：`armed` 等用户在外站页面上动手，`recording` 正在录，`finished` 录完待取。
+ */
+export type RecordPhase = 'armed' | 'recording' | 'finished';
+
+/**
+ * 录制约定的有效期（15 分钟，毫秒）：超过它没动静的约定算过期、当场让人。
+ */
+export const RECORD_STALE_MS = 15 * 60 * 1000;
+
+/**
+ * 这次录制要找的那一次写：HTTP 方法 + URL 里必须含的一段（不填就是只认方法）。
+ */
+export interface RecordExpect {
+  readonly method: string;
+  readonly urlContains: string;
+}
+
+/**
+ * 一份活着的录制约定：相位 + 谁的会话 + 哪个工作区 / 单元 + 页面 URL 与标题 + 要找的那一次写 + 落盘文件 + 三个时间戳。
+ */
+export interface RecordState {
+  readonly phase: RecordPhase;
+  readonly sessionId: string;
+  readonly workspace: string;
+  readonly unit: string;
+  readonly name: string;
+  readonly url: string;
+  readonly title: string;
+  readonly action: string;
+  readonly expect: RecordExpect | null;
+  readonly captureFile: string;
+  readonly startedAt: number;
+  readonly t0: number | null;
+  readonly t1: number | null;
+  readonly at: number;
+}
+
+/**
+ * 开一次录制要交的那几件：会话、工作区、单元、名字、页面 URL 与标题、动作名、期望、落盘文件，以及此刻时间。
+ */
+export interface RecordPact {
+  readonly sessionId: string;
+  readonly workspace: string;
+  readonly unit: string;
+  readonly name: string;
+  readonly url: string;
+  readonly title: string;
+  readonly action: string;
+  readonly expect: RecordExpect | null;
+  readonly captureFile: string;
+  readonly now: number;
+}
+
+/**
+ * 录制被拒的原因码：自己已持有 / 别人持着 / 不是持有者 / 没有约定 / 已在录 / 还没 arm / 不在录 / 还没录完。
+ */
+export type RecordRefusal =
+  | 'already-held'
+  | 'held-by-other'
+  | 'not-owner'
+  | 'none'
+  | 'already-recording'
+  | 'not-armed'
+  | 'not-recording'
+  | 'not-finished';
+
+/**
+ * 一次录制动作的结果：成功带新状态，失败带拒绝码。
+ */
+export type RecordMove =
+  | { readonly ok: true; readonly state: RecordState }
+  | { readonly ok: false; readonly code: RecordRefusal };
+
+/**
+ * 录制约定收得下的三个人话动作：看看进度 / 停手 / 结束并取回。
+ */
+export type RecordIntent = 'peek' | 'halt' | 'stop';
+
+/**
+ * 把工具入参收成人话动作。
+ * @param raw - 任意入参值。
+ * @returns `'peek'` / `'halt'` / `'stop'` 原样；别的值（含 `undefined`、多余空白）给 `null`，由调用方拒。
+ */
+export function parseRecordIntent(raw: unknown): RecordIntent | null {
+  return raw === 'peek' || raw === 'halt' || raw === 'stop' ? raw : null;
+}
+
+/**
+ * 录制约定的存取口（外壳持有一份）：相位随 `begin → started → finished` 推进，`release` 是收尾时放掉浏览器那一跳。
+ */
+export interface RecordStore {
+  readonly release?: ((state: RecordState) => Promise<{ readonly tab: boolean; readonly capture: boolean }>) | undefined;
+  live(now: number): RecordState | null;
+  begin(pact: RecordPact): RecordMove;
+  started(sessionId: string, at: number, now: number): RecordMove;
+  finished(sessionId: string, at: number, now: number): RecordMove;
+  stop(sessionId: string, now: number): RecordMove;
+}
+
+function alive(state: RecordState | null, now: number): RecordState | null {
+  if (state === null) return null;
+  return now - state.at <= RECORD_STALE_MS ? state : null;
+}
+
+function ownerOf(state: RecordState | null, sessionId: string, now: number): RecordRefusal | RecordState {
+  const held = alive(state, now);
+  if (held === null) return 'none';
+  return held.sessionId === sessionId ? held : 'not-owner';
+}
+
+/**
+ * 造一份新的录制约定存储（进程内存，同一时刻只可能有一份有效约定）。
+ * @returns 存取口；动作成不成都在返回的 `RecordMove` 里，不抛异常。
+ */
+export function createRecordStore(): RecordStore {
+  let held: RecordState | null = null;
+
+  const live = (now: number): RecordState | null => 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: RecordState = {
+        phase: 'armed',
+        sessionId: pact.sessionId,
+        workspace: pact.workspace,
+        unit: pact.unit,
+        name: pact.name,
+        url: pact.url,
+        title: pact.title,
+        action: pact.action,
+        expect: pact.expect,
+        captureFile: pact.captureFile,
+        startedAt: pact.now,
+        t0: null,
+        t1: null,
+        at: pact.now,
+      };
+      held = state;
+      return { ok: true, state };
+    },
+
+    started(sessionId, at, now) {
+      const found = ownerOf(held, sessionId, now);
+      if (typeof found === 'string') return { ok: false, code: found };
+      if (found.phase === 'recording') return { ok: false, code: 'already-recording' };
+      if (found.phase !== 'armed') return { ok: false, code: 'not-armed' };
+      const state: RecordState = { ...found, phase: 'recording', t0: at, at: now };
+      held = state;
+      return { ok: true, state };
+    },
+
+    finished(sessionId, at, now) {
+      const found = ownerOf(held, sessionId, now);
+      if (typeof found === 'string') return { ok: false, code: found };
+      if (found.phase !== 'recording') return { ok: false, code: 'not-recording' };
+      const state: RecordState = { ...found, phase: 'finished', t1: at, 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 };
+    },
+  };
+}
+
+/**
+ * 「谁还占着、在录哪个动作」的一句话，用于别人来抢时说清现况。
+ * @param state - 当前有效的那份约定。
+ * @returns 形如「会话 x（自 HH:mm:ssZ 起在录 y 的「动作」）」的中文串。
+ */
+export function recordOwnerText(state: RecordState): string {
+  const at = new Date(state.startedAt).toISOString().slice(11, 19);
+  return `会话 ${state.sessionId}（自 ${at}Z 起在录 ${state.unit} 的「${state.action}」）`;
+}

package/src/lib/form-problem.ts

@@ -9,10 +9,20 @@ const FOCUSABLE_SELECTOR = [
   '[tabindex]:not([tabindex="-1"])',
 ].join(', ');
 
+/**
+ * 找 `root` 里第一个带 `[data-wb-problem]` 标记的元素 —— 表单校验失败时，调用方拿它定位「哪一格错了」。
+ * @param root - 要搜的范围（表单容器，或 document）。
+ * @returns 第一个出问题的元素；一个标记都没有就给 `null`。
+ */
 export function firstProblemOf(root: ParentNode): Element | null {
   return root.querySelector(PROBLEM_SELECTOR);
 }
 
+/**
+ * 把第一个出问题的元素滚进视野、并把焦点交给它里面第一个可聚焦控件（输入框 / 按钮 / 链接等）。
+ * @param root - 要搜的范围。
+ * @returns 找到并滚过给 `true`；没有问题给 `false`（不滚、不抢焦点）；元素不可滚或没有可聚焦控件也不报错，只是少做一步。
+ */
 export function revealFirstProblem(root: ParentNode): boolean {
   const problem = firstProblemOf(root);
   if (problem === null) return false;

package/src/lib/panel-state.ts

@@ -1,10 +1,19 @@
+/**
+ * 一张面板卡片取数走到哪一步：`idle` 还没取、`loading` 取着、`ready` 拿到了、`error` 失败了。
+ */
 export type PanelCardPhase = 'idle' | 'loading' | 'ready' | 'error';
 
+/**
+ * 一次取数失败：机器码 + 给人看的一句话。
+ */
 export interface PanelCardError {
   readonly code: string;
   readonly message: string;
 }
 
+/**
+ * 一张卡片最近一次取数的读数：哪个单元、哪条路由、什么相位、什么时候、失败原因。
+ */
 export interface PanelCardRead {
   readonly unit: string;
   readonly route: string;
@@ -13,6 +22,9 @@ export interface PanelCardRead {
   readonly error?: PanelCardError;
 }
 
+/**
+ * 一张卡片崩了的读数：单元、原因、时间，以及同一原因连着崩了几次（窗口见 `PANEL_STATE_CRASH_WINDOW_MS`）。
+ */
 export interface PanelCardCrash {
   readonly unit: string;
   readonly reason: string;
@@ -20,6 +32,9 @@ export interface PanelCardCrash {
   readonly count: number;
 }
 
+/**
+ * 一个单元此刻的读数：它的卡片、最近一次读成的时间（`okAt`，没成过给 `null`），以及崩了的那一条。
+ */
 export interface PanelUnitReport {
   readonly unit: string;
   readonly at: number;
@@ -28,17 +43,26 @@ export interface PanelUnitReport {
   readonly crash?: PanelCardCrash;
 }
 
+/**
+ * 一个工作区此刻的全量读数（面板按工作区存）：所有单元的读数 + 整块最近动过的时间。
+ */
 export interface PanelWorkspaceReport {
   readonly workspace: string | null;
   readonly at: number;
   readonly units: readonly PanelUnitReport[];
 }
 
+/**
+ * 客户端往上报的一批卡片读数（`POST` 请求体的形状）。
+ */
 export interface PanelCardsReport {
   readonly workspace: string;
   readonly cards: readonly PanelCardRead[];
 }
 
+/**
+ * 客户端往上报的一次卡片崩溃（`POST` 请求体的形状）。
+ */
 export interface PanelCrashReport {
   readonly workspace: string;
   readonly unit: string;
@@ -46,16 +70,34 @@ export interface PanelCrashReport {
   readonly at: number;
 }
 
+/**
+ * 面板运行态的留存口（宿主持有一份）：收卡片读数与崩溃，按工作区取快照。
+ */
 export interface PanelStateStore {
   cards(report: PanelCardsReport): void;
   crash(report: PanelCrashReport): void;
   snapshot(workspace: string | null): PanelWorkspaceReport;
 }
 
+/**
+ * 留存的工作区上限（LRU，满 64 个丢最旧的）。
+ */
 export const PANEL_STATE_MAX_UNITS = 64;
+/**
+ * 每个单元留存的卡片上限（按路由 LRU，满 12 张丢最旧的）。
+ */
 export const PANEL_STATE_MAX_CARDS = 12;
+/**
+ * 一次上报最多读入的卡片条数（32 条之后的丢掉）。
+ */
 export const PANEL_STATE_MAX_REPORTS = 32;
+/**
+ * 同一原因的连续崩溃算进同一次计数的窗口（10 分钟，毫秒）。
+ */
 export const PANEL_STATE_CRASH_WINDOW_MS = 600000;
+/**
+ * 上报文本字段的截断长度（2000 字符；workspace / reason / message 共用）。
+ */
 export const PANEL_STATE_MAX_TEXT = 2000;
 
 const PHASES: readonly PanelCardPhase[] = ['idle', 'loading', 'ready', 'error'];
@@ -71,6 +113,9 @@ interface WorkspaceEntry {
   units: Map<string, UnitEntry>;
 }
 
+/**
+ * 上报解析的结果：`ok: true` 带收好的值，`ok: false` 带一句中文原因（直接回给上报方）。
+ */
 export type PanelParse<T> =
   | { readonly ok: true; readonly value: T }
   | { readonly ok: false; readonly message: string };
@@ -100,6 +145,12 @@ function errorOf(raw: unknown): PanelCardError | undefined {
   return { code: code === '' ? 'unknown' : code, message };
 }
 
+/**
+ * 收一批卡片读数上报。
+ * @param payload - `POST` 的请求体。
+ * @returns 至少收到一条能认的卡片才 `ok: true`；请求体不是对象、`workspace` 为空、`cards` 不是数组，
+ *   或一条都认不出（`unit` / `route` / `phase` / `at` 缺一）时 `ok: false` + 中文原因；认不出的单条静默跳过。
+ */
 export function parseCardsReport(payload: unknown): PanelParse<PanelCardsReport> {
   const record = asRecord(payload);
   if (record === undefined) return { ok: false, message: '请求体要是一个对象' };
@@ -123,6 +174,11 @@ export function parseCardsReport(payload: unknown): PanelParse<PanelCardsReport>
   return { ok: true, value: { workspace, cards } };
 }
 
+/**
+ * 收一次卡片崩溃上报。
+ * @param payload - `POST` 的请求体。
+ * @returns `workspace` / `unit` / `reason` 都不能空，缺一给 `ok: false` + 中文原因；`at` 缺省或不合法时取当前时间。
+ */
 export function parseCrashReport(payload: unknown): PanelParse<PanelCrashReport> {
   const record = asRecord(payload);
   if (record === undefined) return { ok: false, message: '请求体要是一个对象' };
@@ -135,6 +191,10 @@ export function parseCrashReport(payload: unknown): PanelParse<PanelCrashReport>
   return { ok: true, value: { workspace, unit, reason, at: atOf(record['at']) ?? Date.now() } };
 }
 
+/**
+ * 造一份面板运行态的留存（进程内存、按工作区分桶，带上面那几条上限的 LRU）。
+ * @returns 留存口：`cards` / `crash` 收上报，`snapshot(workspace)` 取全量；没存过的工作区（含 `null`）给一份空的。
+ */
 export function createPanelStateStore(): PanelStateStore {
   const workspaces = new Map<string, WorkspaceEntry>();
 

package/src/lib/react.ts

@@ -2,21 +2,60 @@ import type * as ReactTypes from 'react';
 
 const react = require('react') as typeof ReactTypes;
 
+/**
+ * React 的 `createElement` 换个短名字再导出 —— 这套代码用 `h(...)` 写元素。
+ */
 export const h = react.createElement;
 
+/**
+ * React 的 `Fragment` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const Fragment = react.Fragment;
 
+/**
+ * React 的 `Component` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const Component = react.Component;
 
+/**
+ * React 的 `createContext` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const createContext = react.createContext;
+/**
+ * React 的 `useContext` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useContext = react.useContext;
 
+/**
+ * React 的 `useState` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useState = react.useState;
+/**
+ * React 的 `useEffect` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useEffect = react.useEffect;
+/**
+ * React 的 `useLayoutEffect` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useLayoutEffect = react.useLayoutEffect;
+/**
+ * React 的 `useMemo` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useMemo = react.useMemo;
+/**
+ * React 的 `useCallback` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useCallback = react.useCallback;
+/**
+ * React 的 `useRef` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useRef = react.useRef;
+/**
+ * React 的 `useSyncExternalStore` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useSyncExternalStore = react.useSyncExternalStore;
 
+/**
+ * 从 react 借来的三个类型（`ReactNode` / `CSSProperties` / `ChangeEvent`）—— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export type { ReactNode, CSSProperties, ChangeEvent } from 'react';

package/src/lib/text.ts

@@ -1,7 +1,18 @@
+/**
+ * 把一个值裹成 shell 里的单引号字面量（值里的单引号一并转义），保证元字符按字面量传递。
+ * @param value - 任意值；不是字符串的先 `String()`。
+ * @returns 可安全拼进 `/bin/sh -c` 的一段文本 —— 含空格 / `$()` / `;` / 通配符的值都不会被当成语法。
+ */
 export function quoteShellArg(value: unknown): string {
   return `'${String(value).replace(/'/g, `'\\''`)}'`;
 }
 
+/**
+ * 取一段文本的末尾若干行（如命令输出），顺带去掉首尾空白。
+ * @param text - 原文；`null` / `undefined` 当空串。
+ * @param lines - 最多留几行，默认 6；0 给全篇、负数从开头砍掉那么多行（都是 `slice` 语义），调用方传正数。
+ * @returns 末尾若干行、去首尾空行后的文本；原文行数不够就全给，空输入给空串。
+ */
 export function tailLines(text: string | null | undefined, lines = 6): string {
   const all = String(text ?? '')
     .trim()
@@ -24,6 +35,11 @@ function candidateStarts(raw: string): number[] {
   return starts;
 }
 
+/**
+ * 宽松解析一段前后可能夹着人话的 JSON：整段不通就从行首的 `[` / `{` 起、截到最后一个闭合符再试。
+ * @param text - 原文；`null` / `undefined` 当空串。
+ * @returns 解析出的值（对象 / 数组 / 标量都原样）；空输入或怎么都解析不出给 `undefined`，调用方据此报「输出认不出」。
+ */
 export function parseJsonLoose(text: string | null | undefined): unknown {
   const raw = String(text ?? '').trim();
   if (!raw) return undefined;
@@ -48,6 +64,12 @@ const MARKDOWN_IMAGE = /!\[[^\]]*\]\([^)]*\)/g;
 const MARKDOWN_LINK = /\[([^\]]*)\]\([^)]*\)/g;
 const MARKDOWN_MARKS = /[*`_>#]/g;
 
+/**
+ * 把一段 Markdown 压成一行纯文本摘要：图片剥掉、链接只留可见文字、标记符号压成空格，超长按字符截断。
+ * @param text - 原文；`null` / `undefined` 当空串。
+ * @param limit - 摘要最多多少字符，默认 80。
+ * @returns 单行摘要；没超限原样给，超了截到 `limit` 并补省略号（总长 `limit + 1`；第 `limit` 个字符是空白时会被 `trimEnd` 去掉、略短），空输入给空串。
+ */
 export function excerpt(text: string | null | undefined, limit = 80): string {
   const flat = String(text ?? '')
     .replace(MARKDOWN_IMAGE, ' ')

package/src/lib/ui.ts

@@ -1,3 +1,8 @@
+/**
+ * 拼类名：只留真值、用空格连接（`false` / `null` / `undefined` / 空串都丢掉）。
+ * @param parts - 若干类名或条件值。
+ * @returns 拼好的类字符串；一个真值都没有给空串。
+ */
 export function cx(...parts: Array<string | false | null | undefined>): string {
   return parts.filter(Boolean).join(' ');
 }
@@ -8,15 +13,30 @@ const DAY = 24 * HOUR;
 const MONTH = 30 * DAY;
 const YEAR = 365 * DAY;
 
+/**
+ * 时间文案取词：i18n 的 `(key, params) => 文案`；相对时间那几件都从它拿词。
+ */
 export type TimeTranslate = (key: string, params?: Record<string, unknown>) => string;
 
+/**
+ * 相对时间的档位名，对应词表里的 `time.short.*`。
+ */
 export type RelativeTimeUnit = 'now' | 'minutes' | 'hours' | 'days' | 'months' | 'years';
 
+/**
+ * 相对时间的一档：`unit` 是档位，`n` 是这一档的数量（单位随档位，见 `relativeTimeBucket`）。
+ */
 export interface RelativeTimeBucket {
   readonly unit: RelativeTimeUnit;
   readonly n: number;
 }
 
+/**
+ * 把时间戳按 dsh 的分档切成「刚刚 / N 分钟 / N 小时 / N 天 / N 月 / N 年」—— 30 天进月、365 天进年。
+ * @param epochMs - 要换算的时间戳（毫秒）。
+ * @param now - 基准时间，默认 `Date.now()`。
+ * @returns 档位与数量；时间戳或基准不是有限数给 `null`，未来时间钳到「刚刚」（`now` / 0）。
+ */
 export function relativeTimeBucket(epochMs: number, now: number = Date.now()): RelativeTimeBucket | null {
   if (!Number.isFinite(epochMs) || !Number.isFinite(now)) return null;
   const diff = Math.max(0, now - epochMs);
@@ -32,11 +52,25 @@ function bucketLabel(bucket: RelativeTimeBucket, t: TimeTranslate): string {
   return bucket.unit === 'now' ? t('time.now') : t(`time.short.${bucket.unit}`, { n: bucket.n });
 }
 
+/**
+ * 行内用的紧凑相对时间（「3 分钟」这种，不带「前」）。
+ * @param epochMs - 要换算的时间戳（毫秒）。
+ * @param t - 词表取词函数。
+ * @param now - 基准时间，默认 `Date.now()`。
+ * @returns 紧凑文案；时间戳非法给空串。
+ */
 export function relativeTimeCompact(epochMs: number, t: TimeTranslate, now?: number): string {
   const bucket = relativeTimeBucket(epochMs, now);
   return bucket === null ? '' : bucketLabel(bucket, t);
 }
 
+/**
+ * 悬停卡里用的相对时间（「3 分钟前」）；「刚刚」那一档不加「前」。
+ * @param epochMs - 要换算的时间戳（毫秒）。
+ * @param t - 词表取词函数。
+ * @param now - 基准时间，默认 `Date.now()`。
+ * @returns 带「前」的文案；时间戳非法给空串。
+ */
 export function relativeTimeAgo(epochMs: number, t: TimeTranslate, now?: number): string {
   const bucket = relativeTimeBucket(epochMs, now);
   if (bucket === null) return '';
@@ -44,6 +78,12 @@ export function relativeTimeAgo(epochMs: number, t: TimeTranslate, now?: number)
   return bucket.unit === 'now' ? label : t('time.ago', { t: label });
 }
 
+/**
+ * 会话行那一版相对时间：一小时内按分钟、一天内按小时、七天内按天，再久直接给绝对时间（到秒）。
+ * @param epochMs - 要换算的时间戳（毫秒）。
+ * @param t - 词表取词函数。
+ * @returns 文案；时间戳不是有限数给空串，未来时间落「刚刚」，七天及以上给本地化的年月日时分秒。
+ */
 export function relativeTime(epochMs: number, t: TimeTranslate): string {
   if (!Number.isFinite(epochMs)) return '';
   const diff = Date.now() - epochMs;
@@ -61,6 +101,11 @@ export function relativeTime(epochMs: number, t: TimeTranslate): string {
   });
 }
 
+/**
+ * 把 `/Users/<用户名>/…` 缩成 `~/…`，免得会话行里全是一样的长前缀。
+ * @param path - 任意值。
+ * @returns 缩好的路径；不在用户主目录下原样返回，不是字符串给空串。
+ */
 export function shortenPath(path: unknown): string {
   if (typeof path !== 'string') return '';
   const hit = path.match(/^\/Users\/[^/]+/);
@@ -69,6 +114,11 @@ export function shortenPath(path: unknown): string {
 
 const LOCAL_TIMESTAMP = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})$/;
 
+/**
+ * 解析不带时区的本地时间戳（`YYYY-MM-DD HH:mm:ss`，也接受 `T` 分隔），按本机时区换算。
+ * @param text - 原文；`null` / `undefined` 当空串；首尾空白容忍。
+ * @returns 毫秒时间戳；形态不认识给 `NaN`（调用方据此回退到原始字符串，宁可不换算也不显示错时间）。
+ */
 export function parseLocalTimestamp(text: string | null | undefined): number {
   const raw = String(text ?? '').trim();
   if (!LOCAL_TIMESTAMP.test(raw)) return Number.NaN;