@morlay/dsh-client-modules 0.0.0-stage → 0.2.6

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Client Modules",
+    "description": "Dev-form web layer: serves the page, the app entry and every client resource through an in-process vite dev server (the node-side counterpart of upstream client-modules, with the module table replaced by vite's resolver, prebundling and HMR)."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "客户端模块",
+    "description": "开发态的前端服务：页面、入口与全部客户端资源都由进程内的 vite dev server 提供（上游 client-modules 的 node 半，模块表那一套换成 vite 的解析、预打包与 HMR）。"
+  }
+}

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@morlay/dsh-client-modules",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.6",
+  "description": "Dev-form web layer for dsh: serves the page, the app entry and every client resource through an in-process vite dev server (middleware mode) — the node-side counterpart of upstream @deepseek-ai/dsh-client-modules, with the module table replaced by vite's resolver, dependency prebundling and HMR.",
+  "keywords": [
+    "client",
+    "dsh",
+    "dsh-plugin",
+    "host",
+    "vite"
+  ],
+  "license": "MIT",
+  "author": "morlay",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/morlay/dsh-plugin.git"
+  },
+  "files": [
+    "src",
+    "app-boot",
+    "dist",
+    "locale/*.json"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json",
+    "./client": {
+      "types": "./dist/client.d.mts",
+      "import": "./dist/client.mjs",
+      "default": "./dist/client.mjs"
+    },
+    "./locale/*.json": "./locale/*.json"
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-client-ui-theme": "^0.2.1-alpha.5",
+    "@deepseek-ai/dsh-host-webserver": "^0.2.1-alpha.5",
+    "@morlay/dsh-cordis-assets": "0.2.6",
+    "@oxc-project/runtime": "^0.153.0",
+    "lightningcss": "^1.30.0",
+    "vite": "^8.3.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.5-alpha.2",
+    "@local/devkit": "0.1.0",
+    "@types/node": "^26.5.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.5-alpha.2",
+    "react": "^18.3.1",
+    "rolldown": "^1.2.14"
+  },
+  "engines": {
+    "node": ">=24.11.0"
+  },
+  "dsh": {
+    "client": {
+      "platform": "web",
+      "inject": []
+    }
+  },
+  "scripts": {
+    "build": "pnpm exec tsdown"
+  }
 }

package/src/__tests__/bundle.spec.ts

@@ -0,0 +1,235 @@
+/**
+ * 产出的行为：联邦地址的形态，与"按请求触发、按包聚合"的缓存语义。
+ *
+ * 缓存那条最要紧：产物目录是**包级**的（出口各有自己的文件），而构建是按请求逐出口触发的——命中判据
+ * 少了"这次要的出口在不在"，第二次请求的出口就会 404；构建之间不排队，并发请求会互相删掉对方的产物。
+ */
+import { appendFile, mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, expect, test } from "vitest";
+import { BUNDLER_REV, bundlePackage, clientModulesAlias, urlOf } from "../bundle.ts";
+
+const repoRoot = process.cwd();
+
+test("包级引用的出口按「是不是行」分：行 → client.js，普通 npm 包 → 根出口 index.js", () => {
+  const tables = {
+    versions: new Map([
+      ["@deepseek-ai/dsh-x", "1.2.3"],
+      ["react", "18.3.1"],
+    ]),
+    // 行由 loader 给（`dsh.client` + client 半）；react 是普通 npm 包，不在里面。
+    clientRows: new Set(["@deepseek-ai/dsh-x"]),
+  };
+  expect(urlOf("@deepseek-ai/dsh-x", tables)).toBe(
+    `/@client-modules/@deepseek-ai+dsh-x@1.2.3/client.js?v=${BUNDLER_REV}`,
+  );
+  expect(urlOf("react", tables)).toBe(`/@client-modules/react@18.3.1/index.js?v=${BUNDLER_REV}`);
+});
+
+test("地址带 `?v=`（构建世代；与 vite 同名的参数）", () => {
+  const tables = { versions: new Map([["react", "18.3.1"]]) };
+  expect(urlOf("react", tables)).toBe(`/@client-modules/react@18.3.1/index.js?v=${BUNDLER_REV}`);
+});
+
+test("子路径引用保留子路径；扩展名与产物一致（没有扩展名的补 `.js`，有的原样）", () => {
+  const tables = {
+    versions: new Map([
+      ["@oxc-project/runtime", "0.153.0"],
+      ["katex", "0.16.47"],
+    ]),
+  };
+  // 产物名一律 `<出口名>.js`（`entryFileNames`），所以没扩展名的子路径要补上——不然一半 URL 带、一半不带。
+  expect(urlOf("@oxc-project/runtime/helpers/decorate", tables)).toBe(
+    `/@client-modules/@oxc-project+runtime@0.153.0/helpers/decorate.js?v=${BUNDLER_REV}`,
+  );
+  expect(urlOf("katex/dist/katex.min.css", tables)).toBe(
+    `/@client-modules/katex@0.16.47/dist/katex.min.css?v=${BUNDLER_REV}`,
+  );
+});
+
+let work: string;
+let cacheRoot: string;
+let packageRoot: string;
+
+beforeAll(async () => {
+  work = await mkdtemp(join(tmpdir(), "dsh-bundle-"));
+  cacheRoot = join(work, ".cache");
+  packageRoot = join(work, "fixture");
+  await mkdir(join(packageRoot, "src"), { recursive: true });
+  await writeFile(
+    join(packageRoot, "src", "a.ts"),
+    [
+      "function Remote(): MethodDecorator { return () => undefined; }",
+      "export class Registry {",
+      "  @Remote()",
+      "  list(): string[] { return []; }",
+      "}",
+      "",
+    ].join("\n"),
+    "utf8",
+  );
+  // 这个包声明的运行期依赖（外置名单从这里来）。
+  await writeFile(
+    join(packageRoot, "package.json"),
+    `${JSON.stringify({ name: "fixture", dependencies: { zod: "^4.0.0" } })}\n`,
+    "utf8",
+  );
+  // 与 profile 同形：编译设置**在解析根里**（打包形态是 profile，dev 是工作区）。
+  await writeFile(
+    join(work, "tsconfig.json"),
+    `${JSON.stringify({ compilerOptions: { target: "esnext", experimentalDecorators: true } })}\n`,
+    "utf8",
+  );
+  await writeFile(join(packageRoot, "src", "b.ts"), "export const b = 2;\n", "utf8");
+});
+
+afterAll(async () => {
+  await rm(work, { recursive: true, force: true });
+});
+
+function options(exportName: string): Parameters<typeof bundlePackage>[0] {
+  return {
+    cacheRoot,
+    repoRoot: work,
+    alias: clientModulesAlias({
+      repoRoot,
+      nodeStub: join(repoRoot, "packages/client/dsh-client-modules/app-boot/node-stub.cjs"),
+    }),
+    name: "fixture",
+    version: "1.0.0",
+    input: { [exportName]: join(packageRoot, "src", `${exportName}.ts`) },
+    watch: [join(packageRoot, "src")],
+  };
+}
+
+test("按出口命中：先请求 a、再请求 b，b 不该被当成命中，且 a 的产物要留下", async () => {
+  const first = await bundlePackage(options("a"));
+  expect([...(first?.files.keys() ?? [])]).toEqual(["a"]);
+  const second = await bundlePackage(options("b"));
+  expect([...(second?.files.keys() ?? [])].sort()).toEqual(["a", "b"]);
+  // 增量合并：a 的产物还在磁盘上（没被这次构建清掉）。
+  const aFile = join(cacheRoot, first?.files.get("a") ?? "");
+  await expect(stat(aFile)).resolves.toBeDefined();
+});
+
+test("已产出的出口再次请求：命中缓存，不重打（产物的 mtime 不变）", async () => {
+  const target = join(cacheRoot, "fixture@1.0.0", "a.js");
+  const before = await stat(target);
+  await new Promise((resolve) => setTimeout(resolve, 20));
+  await bundlePackage(options("a"));
+  const after = await stat(target);
+  expect(after.mtimeMs).toBe(before.mtimeMs);
+});
+
+test("地址与产物内容无关：构建前后是同一个 URL（内容变了靠协商缓存，URL 不裂成两个）", async () => {
+  const tables = { versions: new Map([["fixture", "1.0.0"]]) };
+  const before = urlOf("fixture", tables);
+  await bundlePackage(options("a"));
+  expect(urlOf("fixture", tables)).toBe(before);
+});
+
+test("源码变了：指纹变、重打（且旧产物作废）", async () => {
+  const first = await bundlePackage(options("a"));
+  await appendFile(join(packageRoot, "src", "a.ts"), "export const a2 = 3;\n", "utf8");
+  const second = await bundlePackage(options("a"));
+  expect(second?.rev).not.toBe(first?.rev);
+});
+
+test("装饰器在产物里必须已被转译，且**不依赖进程 cwd**", async () => {
+  // 这条是"不同工作目录要有一致行为"的守卫：vite build（rolldown 的 oxc）默认按 **cwd** 找 tsconfig，
+  // 而这条链在打包形态下跑在宿主进程里（cwd 是宿主的，不是解析根）——少了这条，上游用 cordis 装饰器的包
+  // 就会在产物里原样留着 `@Remote(...)`，浏览器报 `SyntaxError`、入口整条不执行。
+  const elsewhere = await mkdtemp(join(tmpdir(), "dsh-bundle-cwd-"));
+  const before = process.cwd();
+  process.chdir(elsewhere);
+  try {
+    const bundled = await bundlePackage(options("a"));
+    const code = await readFile(join(cacheRoot, bundled?.files.get("a") ?? ""), "utf8");
+    expect(code).not.toMatch(/@Remote/u);
+    expect(code).toMatch(/__decorate|_ts_decorate|decorate/u);
+  } finally {
+    process.chdir(before);
+    await rm(elsewhere, { recursive: true, force: true });
+  }
+});
+
+test("包住在没有 tsconfig 祖先的地方时，`resolve.tsconfigFilename` 也能让它转", async () => {
+  // 外置/官方的包就住在 `node_modules/.pnpm/…` 里——向上找不到任何 tsconfig。这条守着那个开关：
+  // 只给 `transform.decorator`（实测 vite 不带进 rolldown）不行，`resolve.tsconfigFilename` 才行。
+  const work2 = await mkdtemp(join(tmpdir(), "dsh-bundle-tsfn-"));
+  const pkg2 = join(work2, "node_modules", "fixture");
+  await mkdir(join(pkg2, "src"), { recursive: true });
+  await writeFile(
+    join(pkg2, "src", "a.ts"),
+    [
+      "function Remote(): MethodDecorator { return () => undefined; }",
+      "export class Registry {",
+      "  @Remote()",
+      "  list(): string[] { return []; }",
+      "}",
+      "",
+    ].join("\n"),
+    "utf8",
+  );
+  // tsconfig 放在**解析根之外**（那个包在 `work2/node_modules/…`，祖先链里没有 tsconfig），由
+  // `resolve.tsconfigFilename` 显式指过去——这正是外置/官方包在产物里的处境。
+  const elsewhere = join(work2, "..", `dsh-tsconfig-${String(Date.now())}`, "tsconfig.json");
+  await mkdir(join(elsewhere, ".."), { recursive: true });
+  await writeFile(
+    elsewhere,
+    `${JSON.stringify({ compilerOptions: { target: "esnext", experimentalDecorators: true } })}\n`,
+    "utf8",
+  );
+  try {
+    const bundled = await bundlePackage({
+      cacheRoot: join(work2, ".cache"),
+      repoRoot: work2,
+      alias: [],
+      name: "fixture",
+      version: "1.0.0",
+      input: { a: join(pkg2, "src", "a.ts") },
+      watch: [join(pkg2, "src")],
+      tsconfig: elsewhere,
+    });
+    const code = await readFile(join(join(work2, ".cache"), bundled?.files.get("a") ?? ""), "utf8");
+    // 债已销：这条链改成 **rolldown 直出**（不再经 `vite build`），`resolve.tsconfigFilename` 才落到
+    // rolldown 手里——外置/官方的包住在 `node_modules/.pnpm/…`、祖先链里没有 tsconfig，全靠这里指路。
+    expect(code).not.toMatch(/@Remote/u);
+  } finally {
+    await rm(work2, { recursive: true, force: true });
+    await rm(join(elsewhere, ".."), { recursive: true, force: true });
+  }
+});
+
+test("清单里解析不到的依赖不算可外置候选，也不该让预编译失败", async () => {
+  // 真实里踩到的形状：`zustand` 的 `peerDependencies` 里有 `@types/react`（optional）——类型包不在运行时闭包
+  // 里，于是解析它必然失败。它是**可选** peer、又解析不到，两条都不该让它进候选；若把异常抛出去，死的是
+  // 整个包的预编译（表现为页面上"很多资源加载不了"）。
+  const root = join(work, "absent");
+  await mkdir(join(root, "src"), { recursive: true });
+  await writeFile(join(root, "src", "index.ts"), "export const x = 1;\n", "utf8");
+  await writeFile(
+    join(root, "package.json"),
+    `${JSON.stringify({
+      name: "absent",
+      dependencies: { "@types/absent-types": ">=1" },
+      peerDependencies: { "@types/absent-types": ">=1", "@types/absent-optional": ">=1" },
+      peerDependenciesMeta: { "@types/absent-optional": { optional: true } },
+    })}\n`,
+    "utf8",
+  );
+
+  const built = await bundlePackage({
+    cacheRoot,
+    repoRoot: work,
+    alias: [],
+    name: "absent",
+    version: "1.0.0",
+    input: { index: join(root, "src", "index.ts") },
+    watch: [join(root, "src")],
+    // **本包视角**的清单：现场预编译时由调用方给（外置名单与版本表从它来）——不给就走不到那条路径。
+    manifestOf: join(root, "package.json"),
+  });
+  expect([...(built?.files.keys() ?? [])]).toEqual(["index"]);
+});

package/src/__tests__/resolve.spec.ts

@@ -0,0 +1,127 @@
+/**
+ * 解析面的行为：`exports` 的三种形状、子路径的物理回退、以及"包名没有 `.` 出口"的包怎么找包根。
+ *
+ * 这些都是**dev 形态的联邦寻址**直接依赖的判断——它们错了，浏览器侧表现为一串难归因的 404
+ * 或"模块没有导出 X"。
+ */
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { exportTargetOf, fileInPackage, packageRootOf } from "../resolve.ts";
+
+/** 造一个包（清单 + 文件），用来测"清单说了什么"这一类判断。 */
+async function makePackage(
+  root: string,
+  manifest: unknown,
+  files: Record<string, string>,
+): Promise<void> {
+  await mkdir(root, { recursive: true });
+  await writeFile(join(root, "package.json"), JSON.stringify(manifest, null, 2), "utf8");
+  for (const [path, content] of Object.entries(files)) {
+    const file = join(root, path);
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(file, content, "utf8");
+  }
+}
+
+describe("exportTargetOf", () => {
+  let work: string;
+
+  beforeAll(async () => {
+    work = await mkdtemp(join(tmpdir(), "dsh-resolve-"));
+  });
+
+  afterAll(async () => {
+    await rm(work, { recursive: true, force: true });
+  });
+
+  test("条件**数组**取 `import` 那支（@oxc-project/runtime 的每个出口都是这形状）", async () => {
+    const root = join(work, "array-conditions");
+    await makePackage(
+      root,
+      {
+        name: "array-conditions",
+        version: "1.0.0",
+        exports: {
+          "./helpers/decorate": [
+            {
+              node: "./src/helpers/decorate.js",
+              import: "./src/helpers/esm/decorate.js",
+              default: "./src/helpers/decorate.js",
+            },
+            "./src/helpers/decorate.js",
+          ],
+        },
+      },
+      {
+        "src/helpers/esm/decorate.js": "export default 1;\n",
+        "src/helpers/decorate.js": "module.exports = 1;\n",
+      },
+    );
+    await expect(exportTargetOf(root, "helpers/decorate")).resolves.toBe(
+      join(root, "src/helpers/esm/decorate.js"),
+    );
+  });
+
+  test("没有 `exports` 时退回 `module` → `main`", async () => {
+    const root = join(work, "legacy");
+    await makePackage(
+      root,
+      { name: "legacy", version: "1.0.0", main: "index.js", module: "esm/index.mjs" },
+      { "esm/index.mjs": "export {};\n" },
+    );
+    await expect(exportTargetOf(root, undefined)).resolves.toBe(join(root, "esm/index.mjs"));
+  });
+
+  test("没有 `.` 出口时答不上来（交给物理回退）", async () => {
+    const root = join(work, "no-root-export");
+    await makePackage(
+      root,
+      { name: "no-root-export", version: "1.0.0", exports: { "./posix": "./posix.js" } },
+      { "posix.js": "module.exports = 1;\n" },
+    );
+    await expect(exportTargetOf(root, undefined)).resolves.toBeUndefined();
+  });
+});
+
+describe("fileInPackage", () => {
+  let work: string;
+
+  beforeAll(async () => {
+    work = await mkdtemp(join(tmpdir(), "dsh-file-"));
+  });
+
+  afterAll(async () => {
+    await rm(work, { recursive: true, force: true });
+  });
+
+  test("清单没覆盖的子路径按物理路径找（`picomatch/posix` 就是 `posix.js`）", async () => {
+    const root = join(work, "no-exports");
+    await makePackage(
+      root,
+      { name: "no-exports", version: "1.0.0", main: "index.js" },
+      {
+        "index.js": "module.exports = 1;\n",
+        "posix.js": "module.exports = 2;\n",
+      },
+    );
+    await expect(fileInPackage(root, "posix")).resolves.toBe(join(root, "posix.js"));
+  });
+
+  test("越出包根一律拒绝", async () => {
+    const root = join(work, "bounded");
+    await makePackage(root, { name: "bounded", version: "1.0.0" }, { "index.js": "export {};\n" });
+    await expect(fileInPackage(root, "../escape")).resolves.toBeUndefined();
+  });
+});
+
+test("packageRootOf 认得**没有 `.` 出口**的包（@oxc-project/runtime 只有 ./helpers/*）", async () => {
+  // 从本包自己的清单出发解析：它是这条链声明的运行期依赖（rolldown 注入装饰器 helper 用的那个包）。
+  const found = await packageRootOf(
+    join(process.cwd(), "packages", "client", "dsh-client-modules", "package.json"),
+    "@oxc-project/runtime",
+  );
+  expect(found?.root).toContain("@oxc-project/runtime");
+  expect(found?.version).not.toBe("0");
+});