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

package/dist/lib/panel-state.js

@@ -1,176 +0,0 @@
-/**
- * 留存的工作区上限（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 = ['idle', 'loading', 'ready', 'error'];
-function asRecord(value) {
-    return typeof value === 'object' && value !== null ? value : undefined;
-}
-function textOf(value, max) {
-    if (typeof value !== 'string')
-        return '';
-    const trimmed = value.trim();
-    return trimmed.length > max ? trimmed.slice(0, max) : trimmed;
-}
-function atOf(value) {
-    if (typeof value !== 'number' || !Number.isFinite(value))
-        return null;
-    if (value < 0)
-        return null;
-    return Math.trunc(value);
-}
-function errorOf(raw) {
-    const record = asRecord(raw);
-    if (record === undefined)
-        return undefined;
-    const code = textOf(record['code'], 120);
-    const message = textOf(record['message'], PANEL_STATE_MAX_TEXT);
-    if (code === '' && message === '')
-        return 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) {
-    const record = asRecord(payload);
-    if (record === undefined)
-        return { ok: false, message: '请求体要是一个对象' };
-    const workspace = textOf(record['workspace'], PANEL_STATE_MAX_TEXT);
-    if (workspace === '')
-        return { ok: false, message: 'workspace 不能是空的 —— 面板按工作区存' };
-    const raw = record['cards'];
-    if (!Array.isArray(raw))
-        return { ok: false, message: 'cards 要是一个数组' };
-    const cards = [];
-    for (const item of raw.slice(0, PANEL_STATE_MAX_REPORTS)) {
-        const card = asRecord(item);
-        if (card === undefined)
-            continue;
-        const unit = textOf(card['unit'], 200);
-        const route = textOf(card['route'], 400);
-        const phase = textOf(card['phase'], 20);
-        const at = atOf(card['at']);
-        if (unit === '' || route === '' || at === null || !PHASES.includes(phase))
-            continue;
-        const error = errorOf(card['error']);
-        cards.push({ unit, route, phase, at, ...(error === undefined ? {} : { error }) });
-    }
-    if (cards.length === 0)
-        return { ok: false, message: 'cards 里没有一条能认的（unit / route / phase / at 都要有）' };
-    return { ok: true, value: { workspace, cards } };
-}
-/**
- * 收一次卡片崩溃上报。
- * @param payload - `POST` 的请求体。
- * @returns `workspace` / `unit` / `reason` 都不能空，缺一给 `ok: false` + 中文原因；`at` 缺省或不合法时取当前时间。
- */
-export function parseCrashReport(payload) {
-    const record = asRecord(payload);
-    if (record === undefined)
-        return { ok: false, message: '请求体要是一个对象' };
-    const workspace = textOf(record['workspace'], PANEL_STATE_MAX_TEXT);
-    const unit = textOf(record['unit'], 200);
-    const reason = textOf(record['reason'], PANEL_STATE_MAX_TEXT);
-    if (workspace === '')
-        return { ok: false, message: 'workspace 不能是空的' };
-    if (unit === '')
-        return { ok: false, message: 'unit 不能是空的' };
-    if (reason === '')
-        return { ok: false, message: 'reason 不能是空的（没有原因的崩溃没法查）' };
-    return { ok: true, value: { workspace, unit, reason, at: atOf(record['at']) ?? Date.now() } };
-}
-/**
- * 造一份面板运行态的留存（进程内存、按工作区分桶，带上面那几条上限的 LRU）。
- * @returns 留存口：`cards` / `crash` 收上报，`snapshot(workspace)` 取全量；没存过的工作区（含 `null`）给一份空的。
- */
-export function createPanelStateStore() {
-    const workspaces = new Map();
-    function trim(entry, max) {
-        while (entry.size > max) {
-            const oldest = entry.keys().next();
-            if (oldest.done === true)
-                return;
-            entry.delete(oldest.value);
-        }
-    }
-    function workspaceEntryOf(workspace) {
-        const existing = workspaces.get(workspace);
-        if (existing !== undefined)
-            return existing;
-        const created = { at: 0, units: new Map() };
-        workspaces.set(workspace, created);
-        trim(workspaces, PANEL_STATE_MAX_UNITS);
-        return created;
-    }
-    function unitEntryOf(entry, unit) {
-        const existing = entry.units.get(unit);
-        if (existing !== undefined)
-            return existing;
-        const created = { at: 0, cards: new Map() };
-        entry.units.set(unit, created);
-        return created;
-    }
-    return {
-        cards(report) {
-            const entry = workspaceEntryOf(report.workspace);
-            for (const card of report.cards) {
-                const unit = unitEntryOf(entry, card.unit);
-                unit.cards.delete(card.route);
-                unit.cards.set(card.route, card);
-                trim(unit.cards, PANEL_STATE_MAX_CARDS);
-                if (card.at > unit.at)
-                    unit.at = card.at;
-                if (card.at > entry.at)
-                    entry.at = card.at;
-            }
-        },
-        crash(report) {
-            const entry = workspaceEntryOf(report.workspace);
-            const unit = unitEntryOf(entry, report.unit);
-            const previous = unit.crash;
-            const counted = previous !== undefined &&
-                previous.reason === report.reason &&
-                report.at >= previous.at &&
-                report.at - previous.at <= PANEL_STATE_CRASH_WINDOW_MS;
-            unit.crash = { unit: report.unit, reason: report.reason, at: report.at, count: counted ? previous.count + 1 : 1 };
-            if (report.at > unit.at)
-                unit.at = report.at;
-            if (report.at > entry.at)
-                entry.at = report.at;
-        },
-        snapshot(workspace) {
-            if (workspace === null)
-                return { workspace: null, at: 0, units: [] };
-            const entry = workspaces.get(workspace);
-            if (entry === undefined)
-                return { workspace, at: 0, units: [] };
-            const units = [...entry.units.entries()].map(([unit, one]) => {
-                const cards = [...one.cards.values()].sort((a, b) => a.route.localeCompare(b.route));
-                const okAt = cards.reduce((best, card) => (card.phase === 'ready' && (best === null || card.at > best) ? card.at : best), null);
-                return { unit, at: one.at, okAt, cards, ...(one.crash === undefined ? {} : { crash: one.crash }) };
-            });
-            units.sort((a, b) => b.at - a.at || a.unit.localeCompare(b.unit));
-            return { workspace, at: entry.at, units };
-        },
-    };
-}

package/src/api/__tests__/host-write.test.ts

@@ -1,75 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { writeOutcomeOf, writeRoute } from '../host-write.js';
-
-describe('writeRoute', () => {
-  it('三条通道各自拼得出路由（面板上的写只有这三条）', () => {
-    expect(writeRoute('prefs', 'cmdb')).toBe('prefs/cmdb');
-    expect(writeRoute('actions', 'cmdb-release')).toBe('actions/cmdb-release');
-    expect(writeRoute('provision', '')).toBe('provision');
-  });
-
-  it('provision 忽略资源名（它只发 {action, unit}，没有资源段）', () => {
-    expect(writeRoute('provision', 'issues')).toBe('provision');
-  });
-});
-
-describe('writeOutcomeOf', () => {
-  it('成了 → 值原样交出', () => {
-    const outcome = writeOutcomeOf<{ text: string }>({ ok: true, text: '发出去了' }, '网络不通');
-
-    expect(outcome).toEqual({ ok: true, value: { ok: true, text: '发出去了' } });
-  });
-
-  it('★ 请求没到（null）→ 用调用方给的那句网络文案', () => {
-    expect(writeOutcomeOf(null, '网络不通')).toEqual({ ok: false, message: '网络不通' });
-  });
-
-  it('★ 宿主说失败 → 原样用宿主的话 + detail（不再包一层"操作失败"）', () => {
-    const outcome = writeOutcomeOf(
-      { ok: false, error: { code: 'cmdb/release-blocked', message: '生产环境要先审批', detail: 'job 1234' } },
-      '网络不通',
-    );
-
-    expect(outcome).toEqual({ ok: false, message: '生产环境要先审批', detail: 'job 1234' });
-  });
-
-  it('★ 登录态失效那条错误带着 helpUrl → 一路带出去（卡片才能给「去登录 ↗」而不是"还没绑定"）', () => {
-    const outcome = writeOutcomeOf(
-      {
-        ok: false,
-        error: {
-          code: 'cmdb/login-required',
-          message: 'CMDB 登录态失效了',
-          helpUrl: 'https://cmdb.example.test/login',
-        },
-      },
-      '网络不通',
-    );
-
-    expect(outcome).toEqual({
-      ok: false,
-      message: 'CMDB 登录态失效了',
-      helpUrl: 'https://cmdb.example.test/login',
-    });
-  });
-
-  it('没有 detail 就不给那个字段（别塞一个 undefined 进类型里）', () => {
-    const outcome = writeOutcomeOf({ ok: false, error: { code: 'x', message: '不行' } }, '网络不通');
-
-    expect(outcome).toEqual({ ok: false, message: '不行' });
-    expect(Object.keys(outcome)).not.toContain('detail');
-  });
-
-  it('★ 领域结果那一档（`{ok:false, text}`，没有 `error`）→ 用生产者自己那句话，**不抛异常**', () => {
-    const outcome = writeOutcomeOf(
-      { ok: false, text: 'innettest 没有发布配置（configs 查不到）' } as never,
-      '网络不通',
-    );
-
-    expect(outcome).toEqual({ ok: false, message: 'innettest 没有发布配置（configs 查不到）' });
-  });
-
-  it('★ 连话都没说（`{ok:false}`）→ 用调用方的兜底文案，还是不抛', () => {
-    expect(writeOutcomeOf({ ok: false } as never, '网络不通')).toEqual({ ok: false, message: '网络不通' });
-  });
-});

package/src/api/__tests__/unit-board.test.ts

@@ -1,76 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import type { ModuleBlocker } from '../blocker.js';
-import type { CapabilityPayload } from '../workbench-contract.js';
-import { gateOf, probeKeyOf, splitBlocker } from '../unit-board.js';
-
-function capability(status: CapabilityPayload['status']): CapabilityPayload {
-  return { unit: 'issues', status, required: [], missing: [], detail: '测试用的结论' };
-}
-
-function blocker(id: string, severity: ModuleBlocker['severity']): ModuleBlocker {
-  return { id, severity, title: id, actions: [] };
-}
-
-describe('gateOf（能力门）', () => {
-  it('★ 还没探到（null）→ 照常取数：探测只是个前置检查，不许把卡片按住', () => {
-    expect(gateOf(null, 'capability')).toEqual({ gated: true });
-  });
-
-  it('ok → 取数；缺插件/缺命令 → 不取（那次平台读注定失败）', () => {
-    expect(gateOf(capability('ok'), 'capability')).toEqual({ gated: true });
-    expect(gateOf(capability('missing-plugin'), 'capability')).toEqual({ gated: false });
-    expect(gateOf(capability('missing-commands'), 'capability')).toEqual({ gated: false });
-  });
-
-  it('★ 探不动（unchecked）→ **照常取数**：那是"问不到"，不是"没装"（ADR-0016）', () => {
-    expect(gateOf(capability('unchecked'), 'capability')).toEqual({ gated: true });
-  });
-
-  it("mode: 'none' → 永远取数（套件自己决定不要这道门）", () => {
-    expect(gateOf(capability('missing-plugin'), 'none')).toEqual({ gated: true });
-    expect(gateOf(null, 'none')).toEqual({ gated: true });
-  });
-});
-
-describe('splitBlocker（一条阻断 + 至多一条提示）', () => {
-  it('没有候选 → 两条都没有', () => {
-    expect(splitBlocker([])).toEqual({});
-    expect(splitBlocker([undefined, undefined])).toEqual({});
-  });
-
-  it('★ 第一条 block 赢（一张卡上压两条阻断，用户不知道该按哪个）', () => {
-    const first = blocker('一', 'block');
-    const second = blocker('二', 'block');
-
-    expect(splitBlocker([first, second])).toEqual({ blocker: first });
-  });
-
-  it('只有 notice → 就是 notice（不拦人）', () => {
-    const notice = blocker('降级', 'notice');
-
-    expect(splitBlocker([undefined, notice])).toEqual({ notice });
-  });
-
-  it('★ 有阻断时丢掉提示：那一刻提示只是噪声', () => {
-    const block = blocker('缺插件', 'block');
-    const notice = blocker('降级', 'notice');
-
-    expect(splitBlocker([notice, block])).toEqual({ blocker: block });
-  });
-});
-
-describe('probeKeyOf（出错搭车强探的防抖键）', () => {
-  it('没有错误 → null（调用方据此不探）', () => {
-    expect(probeKeyOf(undefined)).toBeNull();
-  });
-
-  it('★ 键就是错误码：码没变就不再探（否则"错误 → 强探 → 仍然错误"会转圈）', () => {
-    expect(probeKeyOf({ code: 'auth-required', message: '未登录' })).toBe('auth-required');
-    expect(probeKeyOf({ code: 'auth-required', message: '未登录（另一个环境）' })).toBe('auth-required');
-    expect(probeKeyOf({ code: 'missing-plugin', message: '缺插件' })).toBe('missing-plugin');
-  });
-
-  it('空码给一个稳定的兜底键（不许变成"每次都算新错误"）', () => {
-    expect(probeKeyOf({ code: '', message: '没说什么' })).toBe('unknown');
-  });
-});

package/src/api/__tests__/unit.test.ts

@@ -1,38 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { hasEnvSupply, type UnitManifest } from '../unit.js';
-
-function manifest(env?: UnitManifest['env']): UnitManifest {
-  return {
-    id: 'issues',
-    card: { titleKey: 'issues.mine', order: 10 },
-    tools: [],
-    host: { inject: [] },
-    ...(env === undefined ? {} : { env }),
-  };
-}
-
-describe('hasEnvSupply（缺来源时那条回退口径，宿主与浏览器共用一份）', () => {
-  it('声明了插件或库 → 有供给', () => {
-    expect(hasEnvSupply(manifest({ plugins: [{ name: 'coding', commands: ['x'] }] }))).toBe(true);
-    expect(
-      hasEnvSupply(
-        manifest({
-          libs: [
-            {
-              name: 'opencli-workflow',
-              registryEnv: 'WB_NPM',
-              registryDefault: 'https://registry.example/',
-              purpose: '夹具',
-            },
-          ],
-        }),
-      ),
-    ).toBe(true);
-  });
-
-  it('★ 只有基座命令（无卡片模块那种）不算供给 —— 它不是市场门槛，只是缺来源时的回退', () => {
-    expect(hasEnvSupply(manifest({ command: 'gitops' }))).toBe(false);
-    expect(hasEnvSupply(manifest({ plugins: [], libs: [] }))).toBe(false);
-    expect(hasEnvSupply(manifest())).toBe(false);
-  });
-});

package/src/api/unit-board.ts

@@ -1,69 +0,0 @@
-import type { ModuleBlocker } from './blocker.js';
-import type { CapabilityPayload } from './workbench-contract.js';
-import type { ApiError } from './workbench-client.js';
-
-/**
- * 卡片闸的两种档：capability 按环境读数判，none 无条件放行。
- */
-export type GateMode =
-  | 'capability'
-  | 'none';
-
-/**
- * 一次放行判定的结果；gated 为假时卡片不画。
- */
-export interface UnitGate {
-  readonly gated: boolean;
-}
-
-/**
- * 判这张卡现在能不能画。
- * @param capability 环境读数；还没读到给 null。
- * @param mode 闸档。
- * @returns mode 为 none 或读数还没到都放行（先放行让它读）；读到明确不通过（ok 与 unchecked 之外）才拦。
- */
-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' };
-}
-
-/**
- * 一个单元攒下的卡住态：blocker 顶掉卡片，notice 只提示；组装方产出，卡片消费。
- */
-export interface UnitBlockers {
-  readonly blocker?: ModuleBlocker;
-  readonly notice?: ModuleBlocker;
-}
-
-/**
- * 把候选卡住态分档，每档只留第一个。
- * @param candidates 候选（可能含 undefined），按优先级从高到低给。
- * @returns 分出的 blocker 与 notice；已经有 blocker 时不带 notice（挡住就不必再提示）。
- */
-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 }),
-  };
-}
-
-/**
- * 由读口错误算出「出错搭车强探」的防抖键：同一个键只自动重探一次。
- * @param error 读口错误；undefined 表示这次没有错误。
- * @returns 键字符串；空 code 归一到 unknown。
- */
-export function probeKeyOf(error: ApiError | undefined): string | null {
-  if (error === undefined) return null;
-  return error.code === '' ? 'unknown' : error.code;
-}

package/src/api/unit.ts

@@ -1,93 +0,0 @@
-/**
- * 一张卡片在清单里的静态声明（文案键加排序位）；默认显不显示由运行期面板配置定。
- */
-export interface UnitCard {
-  readonly titleKey: string;
-  readonly order: number;
-}
-
-/**
- * 一条工具在清单里的样子：全名加会不会写；审批按 writes 认领。
- */
-export interface UnitTool {
-  readonly name: string;
-  readonly writes: boolean;
-}
-
-/**
- * 模块要外壳的哪些服务：inject 缺一个就挂不上，optional 缺了照挂。
- */
-export interface UnitHostNeeds {
-  readonly inject: readonly string[];
-  readonly optional?: readonly string[];
-}
-
-/**
- * 一个 opencli 插件的来源三选一（git / 本地 / npm）；npm 那支的安装源先看 registryEnv 那个环境变量，没设才用 registryDefault。
- */
-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;
-    };
-
-/**
- * 模块要的一个 opencli 插件：名字、它得提供的命令，以及装它的来源（没写就是不代装）。
- */
-export interface UnitPluginNeed {
-  readonly name: string;
-  readonly commands?: readonly string[];
-  readonly installSource?: PluginSource;
-}
-
-/**
- * 模块要的一个共用库：名字、期望范围与它为什么要这个版本（purpose 会进申报文案）。
- */
-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[];
-}
-
-/**
- * 已装插件与源上最新版那一对，用来判该不该提示升级；latest 缺省表示还没查到。
- */
-export interface PluginRelease {
-  readonly installed: string;
-  readonly latest?: string;
-}
-
-/**
- * 装配期用的模块清单：单元 id、卡片、工具与宿主 / 环境需要，比声明少一层协议包装。
- */
-export interface UnitManifest {
-  readonly id: string;
-  readonly card: UnitCard | null;
-  readonly tools: readonly UnitTool[];
-  readonly host: UnitHostNeeds;
-  readonly env?: UnitEnvNeeds;
-}
-
-/**
- * 判这个模块要不要往外装东西。
- * @param manifest 模块清单。
- * @returns 插件与共用库两张表都空时给 false。
- */
-export function hasEnvSupply(manifest: UnitManifest): boolean {
-  return (manifest.env?.plugins ?? []).length > 0 || (manifest.env?.libs ?? []).length > 0;
-}

package/src/api/workbench-contract.ts

@@ -1,59 +0,0 @@
-import type { PluginRelease } from '../api/unit.js';
-
-/**
- * 供给动作的那几档（装 / 升 / 卸，模块、共用依赖与插件各一套）；写口按它分派。
- */
-export type ProvisionAction =
-  | 'install'
-  | 'update'
-  | 'uninstall'
-  | 'update-dependency'
-  | 'install-bundle'
-  | 'update-bundle'
-  | 'remove-bundle'
-  | 'cancel-install'
-  | 'update-plugin'
-  | 'uninstall-plugin'
-  | 'update-workbench';
-
-/**
- * 宿主报的一个 opencli 插件此刻的状态：装没装、缺哪些命令、该不该升，以及怎么升。
- */
-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' | 'failed' | '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;
-}