@dsh-workbench/module-tools 0.1.14 → 0.1.16

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

@@ -0,0 +1,359 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, describe, expect, it, vi } from 'vitest';
+
+const shell = vi.hoisted(() => ({
+  enabled: false,
+  fixture: undefined as { readonly id: string } | undefined,
+  resource: { phase: 'loading' } as {
+    readonly phase: string;
+    readonly value?: unknown;
+    readonly error?: { readonly code: string; readonly message: string };
+  },
+  readEnabled: undefined as boolean | undefined,
+}));
+
+vi.mock('@dsh-workbench/core/client', () => ({
+  kit: {
+    hooks: {
+      useApiResource: (_route: string, _query: unknown, _refreshToken: number, options?: { readonly enabled?: boolean }) => {
+        shell.readEnabled = options?.enabled;
+        return shell.resource;
+      },
+      useFixturePick: () => ({
+        enabled: shell.enabled,
+        active: shell.fixture?.id ?? null,
+        current: shell.fixture,
+        pick: () => {},
+        nonce: 0,
+        index: 0,
+      }),
+    },
+    components: {
+      Card: () => null,
+      MockStrip: () => null,
+      CenteredState: () => null,
+      EmptyState: () => null,
+      StateBlock: () => null,
+      IconPanelScreen: () => null,
+    },
+  },
+}));
+
+import { apply, inject, name, OVERVIEW_ROUTE, readOverview } from './host';
+import {
+  apply as applyClient,
+  formatBytes,
+  inject as injectClient,
+  overviewFixtures,
+  overviewStateOf,
+} from './client';
+
+interface HostFace {
+  readonly manifest: { readonly id: string };
+  mount(): { readonly routes: Record<string, (search: URLSearchParams) => Promise<unknown>> };
+}
+
+interface ClientFace {
+  readonly manifest: { readonly id: string };
+  readonly card: (props: {
+    readonly world: { readonly current: { readonly workspace?: { readonly path: string } | null } };
+    readonly refreshToken: number;
+    readonly onRefresh: () => void;
+    readonly t: (key: string) => string;
+  }) => unknown;
+}
+
+interface OverviewAnswer {
+  readonly ok: boolean;
+  readonly path: string;
+  readonly files: number;
+  readonly dirs: number;
+  readonly bytes: number;
+  readonly largest: readonly { readonly name: string; readonly bytes: number; readonly mtime: string }[];
+  readonly error: { readonly code: string; readonly message: string };
+}
+
+function hostFace(): HostFace {
+  const faces: unknown[] = [];
+  const ctx = {
+    get: () => ({
+      register: (face: unknown) => {
+        faces.push(face);
+        return () => {};
+      },
+    }),
+    effect: (effect: () => void | (() => void)) => {
+      effect();
+      return () => {};
+    },
+    logger: { warn: () => {} },
+  };
+  apply(ctx as never);
+  return faces[0] as HostFace;
+}
+
+function clientFace(): ClientFace {
+  const faces: unknown[] = [];
+  const ctx = {
+    get: () => ({
+      registerUnit: (face: unknown) => {
+        faces.push(face);
+        return () => {};
+      },
+    }),
+    effect: (effect: () => void | (() => void)) => {
+      effect();
+      return () => {};
+    },
+  };
+  applyClient(ctx as never);
+  return faces[0] as ClientFace;
+}
+
+function overview(search: Record<string, string>): Promise<unknown> {
+  return hostFace().mount().routes[OVERVIEW_ROUTE](new URLSearchParams(search));
+}
+
+function textOf(value: unknown, out: string[] = []): string[] {
+  if (typeof value === 'string') {
+    out.push(value);
+    return out;
+  }
+  if (typeof value === 'number') {
+    out.push(String(value));
+    return out;
+  }
+  if (typeof value === 'boolean' || value === null || value === undefined) return out;
+  if (Array.isArray(value)) {
+    for (const one of value) textOf(one, out);
+    return out;
+  }
+  if (typeof value === 'object') {
+    const record = value as Record<string, unknown>;
+    const source = 'type' in record && 'props' in record ? (record.props as Record<string, unknown>) : record;
+    for (const one of Object.values(source)) {
+      if (typeof one !== 'function') textOf(one, out);
+    }
+  }
+  return out;
+}
+
+const scratch = mkdtempSync(join(tmpdir(), 'dsh-wb-diy-'));
+afterAll(() => {
+  rmSync(scratch, { recursive: true, force: true });
+});
+
+const cardProps = {
+  world: { current: { workspace: { path: '/tmp/__UNIT__-workspace' } } },
+  refreshToken: 1,
+  onRefresh: () => {},
+  t: (key: string) => key,
+};
+
+describe('__NAME__ 的面', () => {
+  it('插件名就是包名', () => {
+    expect(name).toBe('__NAME__');
+  });
+
+  it('两侧都只注入外壳交出来的那个服务', () => {
+    expect(inject).toEqual(['workbenchUnits']);
+    expect(injectClient).toEqual(['workbenchUnits']);
+  });
+
+  it('宿主半侧与浏览器半侧都把自己的面注册进外壳', () => {
+    expect(hostFace().manifest.id).toBe('__UNIT__');
+    expect(clientFace().manifest.id).toBe('__UNIT__');
+  });
+});
+
+describe('宿主侧的只读路由', () => {
+  it('路由住在自己那一格的命名空间里，且是个 async handler', () => {
+    const routes = hostFace().mount().routes;
+    expect(Object.keys(routes)).toEqual([OVERVIEW_ROUTE]);
+    expect(OVERVIEW_ROUTE).toBe('__UNIT__/overview');
+    expect(typeof routes[OVERVIEW_ROUTE]).toBe('function');
+  });
+
+  it('真读一个目录：文件数 / 目录数 / 总字节 / 最大的几个文件（名字 + 字节 + mtime）', async () => {
+    const dir = join(scratch, 'sample');
+    mkdirSync(join(dir, 'nested'), { recursive: true });
+    writeFileSync(join(dir, 'small.txt'), 'x'.repeat(10));
+    writeFileSync(join(dir, 'mid.log'), 'y'.repeat(50));
+    writeFileSync(join(dir, 'big.bin'), 'z'.repeat(100));
+
+    const answer = (await overview({ path: dir, limit: '2' })) as OverviewAnswer;
+    expect(answer.ok).toBe(true);
+    expect(answer.path).toBe(dir);
+    expect(answer.files).toBe(3);
+    expect(answer.dirs).toBe(1);
+    expect(answer.bytes).toBe(160);
+    expect(answer.largest.map((file) => file.name)).toEqual(['big.bin', 'mid.log']);
+    expect(answer.largest[0]?.bytes).toBe(100);
+    expect(Number.isNaN(Date.parse(answer.largest[0]?.mtime ?? ''))).toBe(false);
+  });
+
+  it('limit 由查询参数管，越界会夹住', async () => {
+    const dir = join(scratch, 'sample');
+    const answer = (await overview({ path: dir, limit: '0' })) as OverviewAnswer;
+    expect(answer.largest).toHaveLength(1);
+  });
+
+  it('path 缺省时回 ok:false 的 no-path，而不是偷偷读宿主进程的工作目录', async () => {
+    const answer = (await overview({})) as OverviewAnswer;
+    expect(answer.ok).toBe(false);
+    expect(answer.error.code).toBe('no-path');
+  });
+
+  it('读不到时交回 ok:false 的 error，而不是抛出去', async () => {
+    const answer = (await overview({ path: join(scratch, 'nope') })) as OverviewAnswer;
+    expect(answer.ok).toBe(false);
+    expect(answer.error.code).toBe('overview-unreadable');
+    expect(answer.error.message.length).toBeGreaterThan(0);
+  });
+
+  it('readOverview 与路由返回的是同一份读数', () => {
+    expect(readOverview(join(scratch, 'sample'), 5).bytes).toBe(160);
+  });
+});
+
+describe('卡片：待机 / 加载 / 就绪 / 就绪但空 / 出错', () => {
+  it('没有选中工作区时不发请求，画待机那一屏', () => {
+    const face = clientFace();
+    shell.enabled = false;
+    shell.fixture = undefined;
+    shell.resource = { phase: 'idle' };
+    const withoutProject = { ...cardProps, world: { current: { workspace: null } } };
+
+    expect(textOf(face.card(withoutProject)).join(' ')).toContain('__UNIT__.needProject');
+    expect(shell.readEnabled).toBe(false);
+
+    shell.resource = { phase: 'loading' };
+    expect(textOf(face.card(cardProps)).join(' ')).not.toContain('__UNIT__.needProject');
+    expect(shell.readEnabled).toBe(true);
+  });
+
+  it('没有工作区时夹具照样能演（夹具优先于待机）', () => {
+    const face = clientFace();
+    shell.enabled = true;
+    shell.fixture = overviewFixtures[0];
+    shell.resource = { phase: 'idle' };
+    const withoutProject = { ...cardProps, world: { current: { workspace: null } } };
+    expect(textOf(face.card(withoutProject)).join(' ')).toContain('/mock/workbench');
+  });
+
+  it('四态各画得出来', () => {
+    const face = clientFace();
+    shell.enabled = false;
+    shell.fixture = undefined;
+
+    shell.resource = { phase: 'loading' };
+    expect(textOf(face.card(cardProps)).join(' ')).toContain('__UNIT__.loading');
+
+    shell.resource = { phase: 'error', error: { code: 'internal', message: 'boom' } };
+    expect(textOf(face.card(cardProps)).join(' ')).toContain('internal: boom');
+
+    shell.resource = {
+      phase: 'ready',
+      value: {
+        ok: true,
+        path: '/real/workbench',
+        files: 2,
+        dirs: 1,
+        bytes: 2048,
+        largest: [{ name: 'big.bin', bytes: 2048, mtime: '2026-01-02T03:04:05.000Z' }],
+      },
+    };
+    const ready = textOf(face.card(cardProps)).join(' ');
+    expect(ready).toContain('/real/workbench');
+    expect(ready).toContain('big.bin');
+    expect(ready).toContain('2.0 KB');
+    expect(ready).toContain('__UNIT__.fileUnit');
+    expect(ready).toContain('__UNIT__.largest');
+
+    shell.resource = {
+      phase: 'ready',
+      value: { ok: true, path: '/real/empty', files: 0, dirs: 0, bytes: 0, largest: [] },
+    };
+    expect(textOf(face.card(cardProps)).join(' ')).toContain('__UNIT__.empty');
+  });
+
+  it('刷新中旧数据还在（不退回加载态）', () => {
+    const face = clientFace();
+    shell.enabled = false;
+    shell.fixture = undefined;
+    shell.resource = {
+      phase: 'loading',
+      value: { ok: true, path: '/real/workbench', files: 1, dirs: 0, bytes: 10, largest: [] },
+    };
+    const text = textOf(face.card(cardProps)).join(' ');
+    expect(text).toContain('/real/workbench');
+    expect(text).not.toContain('__UNIT__.loading');
+  });
+
+  it('只有 mock 模式才挂出夹具条', () => {
+    const face = clientFace();
+    shell.fixture = undefined;
+    shell.resource = { phase: 'loading' };
+
+    shell.enabled = false;
+    expect(textOf(face.card(cardProps)).join(' ')).not.toContain('__UNIT__.mockNote');
+
+    shell.enabled = true;
+    const text = textOf(face.card(cardProps)).join(' ');
+    expect(text).toContain('__UNIT__.mockNote');
+    expect(text).toContain('空目录');
+  });
+});
+
+describe('夹具：?wbMock=1 下三种状态都演得出来', () => {
+  it('三个夹具各自解出一个状态（有数据 / 空 / 读不到）', () => {
+    expect(overviewFixtures.map((fixture) => fixture.id)).toEqual(['ready', 'empty', 'error']);
+    const kinds = overviewFixtures.map(
+      (fixture) =>
+        overviewStateOf({
+          fixture,
+          phase: 'error',
+          value: undefined,
+          error: { code: 'network', message: '夹具优先于真请求' },
+        }).kind,
+    );
+    expect(kinds).toEqual(['ready', 'empty', 'error']);
+  });
+
+  it('夹具优先于真请求：三种都画得出来', () => {
+    const face = clientFace();
+    shell.enabled = true;
+    shell.resource = { phase: 'loading' };
+
+    shell.fixture = overviewFixtures[0];
+    const ready = textOf(face.card(cardProps)).join(' ');
+    expect(ready).toContain('/mock/workbench');
+    expect(ready).toContain('client.js');
+
+    shell.fixture = overviewFixtures[1];
+    expect(textOf(face.card(cardProps)).join(' ')).toContain('__UNIT__.empty');
+
+    shell.fixture = overviewFixtures[2];
+    expect(textOf(face.card(cardProps)).join(' ')).toContain('EACCES');
+  });
+
+  it('夹具数据自己的形状也有人守', () => {
+    const ready = overviewFixtures[0]?.payload;
+    expect(ready?.files).toBeGreaterThan(0);
+    expect(ready?.dirs).toBeGreaterThan(0);
+    expect(ready?.bytes).toBeGreaterThan(0);
+    expect(ready?.largest).toHaveLength(3);
+    expect(Number.isNaN(Date.parse(ready?.largest[0]?.mtime ?? ''))).toBe(false);
+    expect(overviewFixtures[1]?.payload?.files).toBe(0);
+    expect(overviewFixtures[1]?.payload?.largest).toHaveLength(0);
+    expect(overviewFixtures[2]?.error?.message).toContain('EACCES');
+  });
+
+  it('字节格式化不炸也不乱', () => {
+    expect(formatBytes(0)).toBe('0 B');
+    expect(formatBytes(2048)).toBe('2.0 KB');
+    expect(formatBytes(3145728)).toBe('3.0 MB');
+  });
+});

package/template-diy/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "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-diy/types/globals.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 浏览器半侧的运行时垫片。
+ *
+ * dsh 的客户端模块格式是 `window.__ModuleLoader__.load({ id, factory(require) })`，
+ * 所以 `require` 不来自模块系统，而是宿主给的作用域。
+ */
+
+/**
+ * React 19 的 `@types/react` 移除了全局 `JSX` 命名空间，而本工程用的是
+ * **经典 JSX 运行时**（`jsxFactory: "h"`）：`react/jsx-runtime` 不在浏览器模块表里，
+ * 所以不能切到自动运行时。这里把全局命名空间接到 `React.JSX` 上 —— 这是官方迁移说明
+ * 给经典运行时的做法，写完 JSX 就有完整类型，产出仍是 `h(...)`。
+ */
+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 {}
+    /** 有了它，返回 ReactNode 的组件（含 Fragment）才合法 —— React 19 的类型靠这条判断。 */
+    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-diy/vitest.config.ts

@@ -0,0 +1,14 @@
+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'] },
+});