@dsh-workbench/module-tools 1.1.13 → 1.1.14-beta.1

package/template-diy/src/model/prefs.ts.tpl

@@ -0,0 +1,61 @@
+import { UNIT_ID } from './notes';
+
+export const PREF_FILE = 'prefs.json';
+export const PREFS_ROUTE = `${UNIT_ID}/prefs`;
+export const PREFS_RESOURCE = UNIT_ID;
+export const LIMIT_DEFAULT = 5;
+export const LIMIT_MIN = 1;
+export const LIMIT_MAX = 50;
+export const LIMIT_CHOICES = [5, 10, 20] as const;
+
+export interface PrefStore {
+  read(name: string): unknown | null;
+  write(name: string, value: unknown): void;
+  remove(name: string): void;
+}
+
+export interface Prefs {
+  readonly limit: number;
+}
+
+export const DEFAULT_PREFS: Prefs = { limit: LIMIT_DEFAULT };
+
+function recordOf(value: unknown): Record<string, unknown> {
+  return typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : {};
+}
+
+function limitOf(raw: unknown): number | undefined {
+  const parsed = typeof raw === 'number' ? raw : typeof raw === 'string' ? Number(raw) : Number.NaN;
+  if (!Number.isInteger(parsed)) return undefined;
+  if (parsed < LIMIT_MIN || parsed > LIMIT_MAX) return undefined;
+  return parsed;
+}
+
+export function prefsOf(store: PrefStore): Prefs {
+  const stored = recordOf(store.read(PREF_FILE));
+  const limit = limitOf(stored['limit']);
+  return { limit: limit ?? LIMIT_DEFAULT };
+}
+
+export function applyPrefs(store: PrefStore, payload: unknown): { readonly prefs: Prefs } {
+  if (typeof payload !== 'object' || payload === null) {
+    throw new Error('偏好写需要一个对象：{ limit?, reset? }');
+  }
+  const body = payload as Record<string, unknown>;
+  if (body['reset'] === true) {
+    store.remove(PREF_FILE);
+    return { prefs: DEFAULT_PREFS };
+  }
+  if (!Object.prototype.hasOwnProperty.call(body, 'limit')) {
+    throw new Error(`这次偏好写里没有 limit —— 可用 ${String(LIMIT_MIN)}..${String(LIMIT_MAX)} 的整数`);
+  }
+  const limit = limitOf(body['limit']);
+  if (limit === undefined) {
+    throw new Error(
+      `「最大的几个文件」只认 ${String(LIMIT_MIN)}..${String(LIMIT_MAX)} 的整数，收到「${String(body['limit'])}」`,
+    );
+  }
+  const prefs: Prefs = { limit };
+  store.write(PREF_FILE, prefs);
+  return { prefs };
+}

package/template/AGENTS.md.tpl

@@ -1,33 +0,0 @@
-# __NAME__ · agent 工作说明
-
-这个包是工作台模块（单元 `__UNIT__`）。`README.md` 讲模块本身；这份讲 agent 在这份代码里怎么干活。
-
-## 命令
-
-```bash
-pnpm install
-pnpm build        # dist/host.js + client.js
-pnpm typecheck
-pnpm test
-pnpm selfcheck
-pnpm check        # 十三条模块判据
-pnpm lint
-pnpm design check
-```
-
-发布（维护者确认之后）：
-
-```bash
-dsh-wb-module release --target team|public|tarball|git
-```
-
-`--dry-run` 只预览，`--verify` 只核已发布的包。
-
-## 不要
-
-- 手改 `client.js` / `dist/**`：构建产物，改 `src/**` 后重新 build。
-
-## 先读
-
-- `README.md`：模块行为与数据源。
-- 工作台模块指引：`@dsh-workbench/core/skills/workbench-module-diy/`（dsh / 工作台的约束随外壳出货）。

package/template/CHANGELOG.md.tpl

@@ -1,7 +0,0 @@
-# 更新日志
-
-## v0.1.0
-
-### ✨ 新增
-
-- 第一个版本

package/template/README.md.tpl

@@ -1,30 +0,0 @@
-# __NAME__
-
-`__UNIT__` 模块：一个独立的 dsh 插件包，只认外壳的服务名，不认识外壳源码。
-
-```bash
-dsh-wb-module build     # 出 dist/host.js 与套了 loader 壳的 client.js
-dsh-wb-module check     # 契约 / 声明协议 / 产物边界 / 源码边界 / 架构 / dsh 原语 / kit 面 / 卡片渲染 / 独立构建 / 内部标识 / 样式归属 / 不指外壳 / 代码卫生（eslint）
-dsh-wb-module check --only cards   # 十三条可以单跑
-```
-
-包自带的六个脚本（`build` / `typecheck` / `test` / `selfcheck` 是 `check` 的契约判据要求的那四个；`check` 跑全部判据，`lint` 只跑源码卫生那一条）：
-
-```bash
-pnpm build        # 构建产物
-pnpm typecheck    # tsc --noEmit
-pnpm test         # vitest（src/**/*.test.ts）
-pnpm selfcheck    # 构建 + 把 client.js 当浏览器加载器跑一遍，看卡片真进没进外壳
-pnpm check        # dsh-wb-module check
-pnpm lint         # dsh-wb-module lint（`--fix` 就地改文件；`check` 永不动手）
-```
-
-形状：`src/components/HelloCard.tsx` 是卡片，`src/client.tsx` 只注册，`src/host.ts` 是宿主面，
-`src/messages.ts` 是文案；有纯逻辑就放 `src/model/**` 并配一份同目录测试。
-
-## 开发与发布
-
-开发命令见上面的六个脚本；dsh / 工作台的模块约束见工作台模块指引（随外壳出货）；agent 的工作说明见 `AGENTS.md`。
-
-发布（维护者确认之后）：`dsh-wb-module release --target team|public|tarball|git`；
-`--dry-run` 只预览，`--verify` 只核已发布的包。

package/template/arch.config.mjs

@@ -1,2 +0,0 @@
-import { moduleArch } from '@dsh-workbench/module-tools/arch';
-export default moduleArch();

package/template/cordis.patch.yml.tpl

@@ -1,3 +0,0 @@
-- insert:
-    - id: workbench-module-__UNIT__
-      name: '__NAME__'

package/template/eslint.config.mjs

@@ -1,2 +0,0 @@
-import { moduleLint } from '@dsh-workbench/module-tools/lint';
-export default moduleLint({ rootDir: import.meta.dirname });

package/template/package.json.tpl

@@ -1,50 +0,0 @@
-{
-  "name": "__NAME__",
-  "version": "0.1.0",
-  "private": true,
-  "description": "__DESC__",
-  "type": "module",
-  "exports": {
-    ".": "./dist/host.js",
-    "./client": "./client.js"
-  },
-  "files": ["dist", "client.js", "cordis.patch.yml", "CHANGELOG.md"],
-  "scripts": {
-    "build": "dsh-wb-module build",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "selfcheck": "dsh-wb-module build && node scripts/smoke.mjs",
-    "check": "dsh-wb-module check",
-    "lint": "dsh-wb-module lint",
-    "prepack": "dsh-wb-module build"
-  },
-  "dsh": {
-    "bundle": { "patch": "./cordis.patch.yml" },
-    "client": {
-      "platform": "web",
-      "inject": ["@dsh-workbench/core"],
-      "external": ["@dsh-workbench/core/client", "@deepseek-ai/dsh-client-ui-primitives"]
-    },
-    "workbench": {
-      "apiVersion": 3,
-      "unit": "__UNIT__",
-      "title": { "zh": "__UNIT__ 模块", "en": "__UNIT__ module" },
-      "card": { "order": 90 },
-      "tools": [],
-      "host": { "inject": [] }
-    },
-    "workbenchFaces": { "host": "src/host.ts", "client": "src/client.tsx" }
-  },
-  "peerDependencies": { "@dsh-workbench/core": "__SHELL_RANGE__", "react": "*" },
-  "peerDependenciesMeta": { "react": { "optional": true } },
-  "devDependencies": {
-    "@deepseek-ai/dsh-client-ui-primitives": "__DSH_UI_VERSION__",
-    "@dsh-workbench/core": "__SHELL_RANGE__",
-    "@dsh-workbench/module-tools": "__SHELL_RANGE__",
-    "@types/node": "^24.19.0",
-    "@types/react": "^19.3.0",
-    "react": "^19.3.0",
-    "typescript": "5.9",
-    "vitest": "^5.0.2"
-  }
-}

package/template/scripts/smoke.mjs.tpl

@@ -1,192 +0,0 @@
-// 模块包的接线自检：把 client.js 当成浏览器里的加载器那样跑一遍，再把宿主产物当 ESM 跑一遍。
-//
-// 为什么值得有：宿主侧挂没挂上，curl /panels 就能看见；浏览器侧挂没挂上，过去只能靠"刷个页面看看"。
-// 这个脚本复刻 dsh 加载器的**契约**（`window.__ModuleLoader__.load({ id, factory })` + `factory(require)`），
-// 于是"模块注册的卡片到底进没进外壳"变成一条机器判据，而不再是人的眼睛。
-//
-// ★ 这份脚本只验**形状**：它认不出成员名、也不认识你的数据源，所以换数据源、换卡片内容都不用改它。
-//   你自己的那条读该不该跑通，属于你自己 vitest 与 `pnpm selfcheck` 的事。
-//
-// 负例在最后一段：服务不在的时候必须**报出来**，不许静默通过 —— 静默的模块是最难查的那种坏。
-
-const PLUGIN_ID = '__NAME__';
-const UNIT_ID = '__UNIT__';
-const failures = [];
-
-function check(name, ok, detail) {
-  if (ok) {
-    console.log(`✅ ${name}`);
-    return;
-  }
-  failures.push(name);
-  console.log(`❌ ${name}${detail === undefined ? '' : ` —— ${detail}`}`);
-}
-
-/**
- * 什么属性都拿得到、什么调用都返回自己的替身 —— 这样"模块用了 kit 的哪个成员"就不再是
- * 这份脚本要知道的事（`check:cards` 用的是同一招）。真红只留给模块自己的代码。
- */
-function anyStub(path = 'stub') {
-  const target = function () {
-    return anyStub(`${path}()`);
-  };
-  return new Proxy(target, {
-    get(_target, key) {
-      if (key === Symbol.toPrimitive) return () => 0;
-      if (key === Symbol.iterator) return function* () {};
-      if (key === 'then') return undefined;
-      if (key === 'length') return 0;
-      if (key === 'toString') return () => path;
-      return anyStub(`${path}.${String(key)}`);
-    },
-    apply() {
-      return anyStub(`${path}()`);
-    },
-  });
-}
-
-/** 外壳 kit 的替身：**三个桶都必须在** —— 卡片是在模块顶层解构 kit 的，少一个桶是 import 那一刻就抛。 */
-function fakeKit() {
-  return {
-    hooks: new Proxy({}, { get: () => () => anyStub('hook') }),
-    components: new Proxy({}, { get: () => () => null }),
-    api: new Proxy({}, { get: () => () => anyStub('api') }),
-    lib: anyStub('lib'),
-  };
-}
-
-function moduleRequire(name) {
-  if (name === 'react') {
-    // 必须是**真的元素对象**：返回 null 的话，"卡片画得出来"这类断言会永远假红。
-    return { createElement: (type, props, ...children) => ({ type, props: props ?? {}, children }) };
-  }
-  if (name === '@dsh-workbench/core/client') return { kit: fakeKit() };
-  throw new Error(`模块包不该 require ${JSON.stringify(name)}：模块表里只有外壳的 seed 词与外部声明`);
-}
-
-let boot = null;
-globalThis.window = {
-  __ModuleLoader__: {
-    load(entry) {
-      boot = entry;
-    },
-  },
-};
-
-await import(new URL('../client.js', import.meta.url).href);
-
-check('client.js 调用 __ModuleLoader__.load()', boot !== null);
-check('模块 id 等于包名', boot?.id === PLUGIN_ID, boot?.id);
-if (boot === null) {
-  console.error(`\n${failures.length} 条没过`);
-  process.exit(1);
-}
-
-const pluginExports = boot.factory(moduleRequire);
-check(
-  '注入 workbenchUnits（外壳交出来的那个服务名）',
-  Array.isArray(pluginExports.inject) && pluginExports.inject.includes('workbenchUnits'),
-  String(pluginExports.inject),
-);
-check('导出了 apply', typeof pluginExports.apply === 'function');
-
-const faces = [];
-const ctx = {
-  get: (name) =>
-    name === 'workbenchUnits'
-      ? {
-          registerUnit(face) {
-            faces.push(face);
-            return () => {};
-          },
-        }
-      : undefined,
-  effect: (fn) => {
-    fn();
-  },
-};
-
-pluginExports.apply(ctx);
-check('卡片真的注册进了外壳', faces.length === 1, `注册了 ${faces.length} 个`);
-check(`注册的是 ${UNIT_ID} 单元`, faces[0]?.unit === UNIT_ID, faces[0]?.unit);
-check('卡片是个能画的组件', typeof faces[0]?.card === 'function');
-check(
-  '面只交 unit（标题与顺序住在 package.json 的 dsh.workbench 里，由外壳按 unit 交给浏览器）',
-  faces[0]?.manifest === undefined,
-  JSON.stringify(faces[0]?.manifest),
-);
-check(
-  '卡片在空数据下也画得出来（不许抛）',
-  (() => {
-    try {
-      return (
-        faces[0].card({ world: { current: {} }, refreshToken: 0, onRefresh: () => {}, t: (key) => key }) != null
-      );
-    } catch {
-      return false;
-    }
-  })(),
-);
-
-const warnings = [];
-const realWarn = console.warn;
-console.warn = (...args) => warnings.push(args.join(' '));
-pluginExports.apply({
-  get: () => undefined,
-  effect: (fn) => {
-    fn();
-  },
-});
-console.warn = realWarn;
-
-check(
-  '负例：外壳没交服务时必须报出来（不许静默通过）',
-  warnings.some((line) => line.includes('workbenchUnits')),
-  warnings.join(' | '),
-);
-
-// ── 宿主产物：面注册得对不对 ──────────────────────────────────────────────
-const hostExports = await import(new URL('../dist/host.js', import.meta.url).href);
-check('宿主产物导出了 apply', typeof hostExports.apply === 'function');
-check(
-  '宿主产物也注入 workbenchUnits',
-  Array.isArray(hostExports.inject) && hostExports.inject.includes('workbenchUnits'),
-);
-
-const hostFaces = [];
-hostExports.apply({
-  get: (name) =>
-    name === 'workbenchUnits'
-      ? {
-          register(face) {
-            hostFaces.push(face);
-            return () => {};
-          },
-        }
-      : undefined,
-  effect: (fn) => {
-    fn();
-  },
-  logger: { warn: () => {} },
-});
-
-check('宿主面注册进了外壳', hostFaces.length === 1, `注册了 ${hostFaces.length} 个`);
-// 给一份最小 deps：宿主面的 `mount(deps)` 通常要 `deps.ctx.get('shell')` 之类，
-// 不给 deps 的话**任何真的用了 `mount(deps)` 的模块**都会在这里崩 —— 而那不是模块的错。
-let mounted = {};
-try {
-  mounted = hostFaces[0]?.mount({ ctx: { get: () => undefined }, logger: { warn: () => {} } }) ?? {};
-} catch (error) {
-  failures.push(`宿主面的 mount(deps) 抛了：${error.message}`);
-}
-
-const routes = mounted.routes ?? {};
-const strays = Object.keys(routes).filter((key) => key !== UNIT_ID && !key.startsWith(`${UNIT_ID}/`));
-check(`每条路由都住在自己那一格（${UNIT_ID} 或 ${UNIT_ID}/…）`, strays.length === 0, strays.join(', '));
-check(
-  'registerTools() 交得出一份清单（这份模块没有工具时是空数组）',
-  Array.isArray(mounted.registerTools?.()),
-);
-
-console.log(`\n${failures.length === 0 ? '模块自检通过' : `${failures.length} 条没过`}`);
-if (failures.length > 0) process.exit(1);

package/template/src/client.tsx.tpl

@@ -1,22 +0,0 @@
-import type { ClientContext, UnitClientApi, UnitClientFace } from '@dsh-workbench/core/contract';
-import { HelloCard } from './components/HelloCard';
-import { messages } from './messages';
-
-const UNIT_ID = '__UNIT__';
-
-const face: UnitClientFace = {
-  unit: UNIT_ID,
-  messages,
-  card: (props) => HelloCard({ t: props.t, onRefresh: props.onRefresh }),
-};
-
-export const inject = ['workbenchUnits'];
-
-export function apply(ctx: ClientContext): void {
-  const units = ctx.get<UnitClientApi>('workbenchUnits');
-  if (units === undefined) {
-    console.warn(`[${UNIT_ID}] 外壳没有提供 workbenchUnits 服务：这张卡片装不进来`);
-    return;
-  }
-  ctx.effect(() => units.registerUnit(face), `__NAME__: 注册 ${UNIT_ID}`);
-}

package/template/src/components/HelloCard.tsx.tpl

@@ -1,28 +0,0 @@
-import { createElement as h } from 'react';
-import { kit } from '@dsh-workbench/core/client';
-
-const UNIT_ID = '__UNIT__';
-
-const { Card } = kit.components;
-
-type Rendered = ReturnType<typeof h>;
-type Translate = (key: string, params?: Record<string, unknown>) => string;
-
-export interface HelloCardProps {
-  readonly t: Translate;
-  readonly onRefresh: () => void;
-}
-
-export function HelloCard(props: HelloCardProps): Rendered {
-  return h(
-    Card,
-    {
-      t: props.t,
-      title: props.t(`${UNIT_ID}.cardTitle`),
-      refreshing: false,
-      onRefresh: props.onRefresh,
-    },
-    h('p', null, props.t(`${UNIT_ID}.heading`)),
-    h('p', null, props.t(`${UNIT_ID}.body`)),
-  );
-}

package/template/src/host.ts.tpl

@@ -1,21 +0,0 @@
-import type { HostContext, UnitModuleFace, UnitRegistry } from '@dsh-workbench/core/contract';
-
-const UNIT_ID = '__UNIT__';
-
-export const name = '__NAME__';
-
-export const inject = ['workbenchUnits'];
-
-const face: UnitModuleFace = {
-  unit: UNIT_ID,
-  mount: () => ({ routes: {}, registerTools: () => [] }),
-};
-
-export function apply(ctx: HostContext): void {
-  const units = ctx.get<UnitRegistry>('workbenchUnits');
-  if (units === undefined) {
-    ctx.logger?.warn?.(`[${UNIT_ID}] 外壳没有提供 workbenchUnits 服务：这个模块装不进来`);
-    return;
-  }
-  ctx.effect(() => units.register(face), `__NAME__: 注册 ${UNIT_ID}`);
-}

package/template/src/messages.ts.tpl

@@ -1,12 +0,0 @@
-export const messages = {
-  zh: {
-    '__UNIT__.cardTitle': '新模块',
-    '__UNIT__.heading': '这张卡还是空的',
-    '__UNIT__.body': '改 src/client.tsx 画你要的内容，然后跑 dsh-wb-module build。',
-  },
-  en: {
-    '__UNIT__.cardTitle': 'New module',
-    '__UNIT__.heading': 'This card is still empty',
-    '__UNIT__.body': 'Edit src/client.tsx to render what you need, then run dsh-wb-module build.',
-  },
-};

package/template/src/plugin.test.ts.tpl

@@ -1,56 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-import { apply, inject, name } from './host';
-import { apply as applyClient, inject as injectClient } from './client';
-
-vi.mock('@dsh-workbench/core/client', () => ({
-  kit: { components: { Card: () => null } },
-}));
-
-function fakeCtx(service: unknown) {
-  const faces: unknown[] = [];
-  return {
-    faces,
-    ctx: {
-      get: () => service,
-      effect: (effect: () => void | (() => void)) => {
-        effect();
-        return () => {};
-      },
-    },
-  };
-}
-
-describe('__NAME__ 的面', () => {
-  it('插件名就是包名', () => {
-    expect(name).toBe('__NAME__');
-  });
-
-  it('两侧都只注入外壳交出来的那个服务', () => {
-    expect(inject).toEqual(['workbenchUnits']);
-    expect(injectClient).toEqual(['workbenchUnits']);
-  });
-
-  it('宿主半侧把自己的面注册进外壳', () => {
-    const { ctx, faces } = fakeCtx({
-      register: (face: unknown) => {
-        faces.push(face);
-        return () => {};
-      },
-    });
-    apply(ctx as never);
-    expect(faces).toHaveLength(1);
-    expect((faces[0] as { unit: string }).unit).toBe('__UNIT__');
-  });
-
-  it('浏览器半侧把自己的卡片注册进外壳', () => {
-    const { ctx, faces } = fakeCtx({
-      registerUnit: (face: unknown) => {
-        faces.push(face);
-        return () => {};
-      },
-    });
-    applyClient(ctx as never);
-    expect(faces).toHaveLength(1);
-    expect((faces[0] as { unit: string }).unit).toBe('__UNIT__');
-  });
-});

package/template/tsconfig.json

@@ -1,20 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "lib": ["ES2022", "DOM"],
-    "jsx": "react",
-    "jsxFactory": "h",
-    "jsxFragmentFactory": "Fragment",
-    "strict": true,
-    "noUnusedLocals": true,
-    "noImplicitOverride": true,
-    "noEmit": true,
-    "skipLibCheck": true,
-    "isolatedModules": true,
-    "verbatimModuleSyntax": true,
-    "paths": { "@/modules/__UNIT__/*": ["./src/*"] }
-  },
-  "include": ["src/**/*.ts", "src/**/*.tsx", "types/**/*.d.ts"]
-}

package/template/types/globals.d.ts

@@ -1,14 +0,0 @@
-import type * as ReactTypes from 'react';
-
-declare global {
-  namespace JSX {
-    interface Element extends ReactTypes.JSX.Element {}
-    interface ElementClass extends ReactTypes.JSX.ElementClass {}
-    interface IntrinsicElements extends ReactTypes.JSX.IntrinsicElements {}
-
-    type ElementType = ReactTypes.JSX.ElementType;
-    interface IntrinsicAttributes extends ReactTypes.JSX.IntrinsicAttributes {}
-    interface ElementAttributesProperty extends ReactTypes.JSX.ElementAttributesProperty {}
-    interface ElementChildrenAttribute extends ReactTypes.JSX.ElementChildrenAttribute {}
-  }
-}

package/template/vitest.config.ts

@@ -1,14 +0,0 @@
-import { fileURLToPath } from 'node:url';
-import { defineConfig } from 'vitest/config';
-
-const here = (relative: string): string => fileURLToPath(new URL(relative, import.meta.url));
-
-export default defineConfig({
-  resolve: {
-    alias: [
-      { find: /^@\/modules\/__UNIT__\//, replacement: `${here('./src')}/` },
-      { find: /^@\/platforms\/[^/]+\//, replacement: `${here('./src/platforms')}/` },
-    ],
-  },
-  test: { environment: 'node', include: ['src/**/*.test.ts', 'src/**/*.test.tsx'] },
-});