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

package/src/resolve.ts

@@ -0,0 +1,418 @@
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, join, relative, resolve as resolvePath, sep } from "node:path";
+
+// 开发态的 client 资源按**文件**寻址：`/plugins/{pkgName}/{version}/{filepath}`。仓库自己的包都是 TS/ESM
+// 源码（`exports` 在 patch 阶段已改指 `src`），所以逐个文件转译直出即可——浏览器原生 ESM 自己解析依赖，
+// 前端资源之间不再受模块表的行集（`inject`）限制。`version` 段取自包清单：既参与寻址，也天然当
+// cache-busting，不必再挂 `?rev=`。
+//
+// 转译与依赖图交给 vite（dev server 的模块图 + 依赖预打包），这里只做**对外地址**的解析。
+
+/** 路由前缀（沿用上游的 `/plugins`，页面上不改 URL 形态）。 */
+export const PLUGIN_ROUTE = "/plugins";
+
+/** 仓库里的包：包根按真实路径记（软链已解开），供越界校验。 */
+export interface PackageRoot {
+  name: string;
+  version: string;
+  root: string;
+}
+
+/** `@deepseek-ai/dsh-x` → `@deepseek-ai+dsh-x`：包名里的 `/` 在 URL 段里要转义。 */
+/**
+ * **出口名 ↔ 产物文件名**的约定：出口产物的文件名是 `<出口名>.js`。
+ *
+ * 这条规则**只有一处**（这里）：`urlOf` 生成地址、产物路由解析地址，两边都调它——各写一遍"补 `.js` / 剥
+ * `.js`"就会漂（`remote` 与 `remote.js` 两种地址，明明产出过却查不到）。
+ */
+export function entryFileNameOf(exportName: string): string {
+  return `${exportName}.js`;
+}
+
+/**
+ * 地址里的文件名 → 出口名（{@link entryFileNameOf} 的反向）。
+ *
+ * @param file - 地址里最后一段（`client.js`、`remote.js`、`chunks/…`）。
+ * @returns 出口名；没有扩展名的按原样（`index` 是包级引用的缺省出口）。
+ */
+export function exportNameOfFileName(file: string): string {
+  return file.replace(/\.js$/u, "") || "index";
+}
+
+export function encodePackageName(name: string): string {
+  return name.replace("/", "+");
+}
+
+export function decodePackageName(segment: string): string {
+  return segment.replace("+", "/");
+}
+
+/**
+ * 按「包与出口」寻址的解析结果：`/plugins/<pkg>/<export>`。
+ *
+ * 与"按文件"不同：一个出口对应**一份产物**（rolldown 打包，包内相对导入 inline、跨包引用 external 成
+ * 对方出口的 URL）。出口名与文件名不同构（`./client` → `src/client/index.ts`、`./remote` →
+ * `lib/typert.remote-client.ts`），所以寻址只能按清单的 `exports` 来，不能按文件。
+ */
+export interface ExportAddress {
+  name: string;
+  /** 出口名：根出口写成 `.`，其余是清单里的键（`./client`）。 */
+  exportName: string;
+}
+
+/**
+ * 权威寻址：`/plugins/{pkg}/{version}/{export}?rev=…`。
+ *
+ * - `pkg` 里的 `/` 转义成 `+`（`@scope/name` → `@scope+name`）；
+ * - `export` 默认 `_default`（= 清单的 `"."` 出口），其余是出口名（`client` → `"./client"`）；
+ * - `rev` 是 query，可省（服务端按内容算得出来）。
+ *
+ * 三方包与仓库包**同格式**：访问这件事上它们没有区别。
+ */
+export interface PluginAddress {
+  name: string;
+  version: string;
+  /** 出口名：`"."` 或 `"./client"` 这类清单键。 */
+  exportName: string;
+}
+
+/** URL 段里的默认出口写法。 */
+export const DEFAULT_EXPORT_SEGMENT = "_default";
+
+export function parsePluginAddress(url: string): PluginAddress | undefined {
+  const path = url.split("?")[0] ?? "";
+  if (!path.startsWith(`${PLUGIN_ROUTE}/`)) return undefined;
+  const segments = path
+    .slice(PLUGIN_ROUTE.length + 1)
+    .split("/")
+    .filter((segment) => segment !== "");
+  // 不是按包寻址的都放行（上游的 combo `??a,b` 那类；如今资源由 vite 直接服务，这条路只留兜底）。
+  if (segments[0]?.startsWith("??") === true || segments[0]?.startsWith(".") === true)
+    return undefined;
+  const [pkgSegment, version, ...exportSegments] = segments;
+  if (pkgSegment === undefined || version === undefined) return undefined;
+  const exportSegment = exportSegments.join("/");
+  return {
+    name: decodePackageName(pkgSegment),
+    version,
+    exportName:
+      exportSegment === "" || exportSegment === DEFAULT_EXPORT_SEGMENT ? "." : `./${exportSegment}`,
+  };
+}
+
+/**
+ * 条件导出里挑**运行期**入口：`import` > `default` > `require` > `types`。
+ *
+ * 条件是**可嵌套**的（`zustand` 的 `./vanilla` 出口就是
+ * `{ import: { types, default }, default: { types, default } }`），所以命中条件后要继续往里挑——
+ * 只看顶层字符串会跳过 `import` 落到 `default`，拿到 CJS 那支（`vanilla.js` 而不是 `esm/vanilla.mjs`），
+ * 产物里就只剩 `export default require_…`，消费方要的具名导出一个都没有。
+ */
+function pickCondition(entry: unknown): string | undefined {
+  if (typeof entry === "string") return entry;
+  // **数组**形态（`@oxc-project/runtime` 的每个出口都是 `[{ node, import, default }, "./src/…"]`）：
+  // node 的语义是"依次尝试"，这里取第一个答得上来的。
+  if (Array.isArray(entry)) {
+    for (const item of entry) {
+      const picked = pickCondition(item);
+      if (picked !== undefined) return picked;
+    }
+    return undefined;
+  }
+  if (entry === null || typeof entry !== "object") return undefined;
+  const record = entry as Record<string, unknown>;
+  for (const key of ["import", "default", "require", "types"]) {
+    if (!(key in record)) continue;
+    const picked = pickCondition(record[key]);
+    if (picked !== undefined) return picked;
+  }
+  return undefined;
+}
+
+/** 按文件寻址的解析结果：包名 + 包内相对路径（`src/client/index.ts` 这种）。 */
+export interface FileAddress {
+  name: string;
+  version: string;
+  filepath: string;
+}
+
+/**
+ * 工作区包索引：包名 → 包根。
+ *
+ * `pnpm` 的布局只保证"**能解析的**才在"——vendor 里的包、以及当前包没声明为依赖的工作区包，从 importer
+ * 出发都解析不到。但它们是**仓库内的包**（有自己的 `exports`、自己的 `./client` 出口），不该被当成三方。
+ * 所以扫一遍仓库内的清单，懒建一次索引。
+ */
+let workspaceIndex: Promise<Map<string, string>> | undefined;
+
+/** 从某个文件向上找仓库根（`pnpm-workspace.yaml` 那一层）。 */
+export async function workspaceRootOf(from: string): Promise<string | undefined> {
+  let directory = dirname(from);
+  for (;;) {
+    if (
+      await readFile(join(directory, "pnpm-workspace.yaml"), "utf8").then(
+        () => true,
+        () => false,
+      )
+    ) {
+      return directory;
+    }
+    const parent = dirname(directory);
+    if (parent === directory) return undefined;
+    directory = parent;
+  }
+}
+
+/**
+ * 仓库内**命中给定 glob** 的包（包名 + 包根）。
+ *
+ * 预打包与联邦寻址都要它：非开发模块不只是"行"，还有 `ui-primitives` 这种共享库；版本表也要覆盖
+ * 那些没进行清单、却会被外置说明符提到的包（cordis、client-store…）。
+ *
+ * @param from - 解析基准（用来找仓库根）。
+ * @param patterns - 匹配包名的正则。
+ * @returns 命中的包。
+ */
+export async function workspacePackagesMatching(
+  from: string,
+  patterns: readonly RegExp[],
+): Promise<{ name: string; root: string }[]> {
+  const index = await workspaceIndexOf(from);
+  return [...index.entries()]
+    .filter(([name]) => patterns.some((pattern) => pattern.test(name)))
+    .map(([name, root]) => ({ name, root }));
+}
+
+async function workspaceIndexOf(from: string): Promise<Map<string, string>> {
+  workspaceIndex ??= (async () => {
+    const index = new Map<string, string>();
+    const root = await workspaceRootOf(from);
+    if (root === undefined) return index;
+    const { glob } = await import("node:fs/promises");
+    for (const pattern of [
+      "packages/*/*/package.json",
+      "vendor/*/packages/*/*/package.json",
+      // 上游把自己的依赖 vendors 在仓库内（cordis、cosmokit…），它们也参与联邦寻址。
+      "vendor/*/vendor/*/package.json",
+    ]) {
+      for await (const file of glob(pattern, { cwd: root })) {
+        const path = join(root, file);
+        const manifest = JSON.parse(await readFile(path, "utf8").catch(() => "{}")) as {
+          name?: string;
+        };
+        if (manifest.name !== undefined) index.set(manifest.name, dirname(path));
+      }
+    }
+    return index;
+  })();
+  return await workspaceIndex;
+}
+
+/**
+ * 包名 → 包根：走 node 的解析（pnpm 已经把依赖摆好了），**解析入口**再向上找最近的清单。
+ *
+ * 不能用 `resolve('<name>/package.json')`：现代包（`clsx` 这类）的 `exports` 通常不暴露
+ * `./package.json`，那样明明装着也解析不出来。
+ */
+export async function packageRootOf(from: string, name: string): Promise<PackageRoot | undefined> {
+  const bare = name
+    .split("/")
+    .slice(0, name.startsWith("@") ? 2 : 1)
+    .join("/");
+  // 虚拟模块的 id（`\0…`）不是路径：`createRequire` 拿到它会抛，直接跳过这层解析。
+  const require = from.startsWith("\0") ? undefined : createRequire(from);
+  try {
+    if (require === undefined) throw new Error("virtual id: 不走 node 解析");
+    // 只解析**包名**：带子路径的说明符（`pkg/sub`）会要求清单里有对应 `exports` 键，而我们要的是包根。
+    const resolved = require.resolve(bare);
+    const owned = await owningPackageOf(resolved);
+    if (owned !== undefined) return owned;
+  } catch {
+    // 落到下面的候选目录：**没有 `.` 出口**的包（`@oxc-project/runtime` 只有 `./helpers/*`）解析不了
+    // 包名本身，明明装着却"解析不到"。
+  }
+  for (const directory of require?.resolve.paths(bare) ?? []) {
+    const manifest = join(directory, bare, "package.json");
+    if (
+      await readFile(manifest, "utf8").then(
+        () => true,
+        () => false,
+      )
+    ) {
+      const owned = await owningPackageOf(manifest);
+      if (owned !== undefined) return owned;
+    }
+  }
+  const root = (await workspaceIndexOf(from)).get(name);
+  return root === undefined ? undefined : await owningPackageOf(join(root, "package.json"));
+}
+
+/**
+ * 按包清单的 `exports` 解析子路径（`./client` → `./src/client/index.ts`）。
+ *
+ * 不能自己拼 `src/<subpath>`：出口名与文件名**不同构**（`./client` 指向 `src/client/index.ts`、
+ * `./remote` 指向 `lib/typert.remote-client.ts` 这类都由清单说了算）。
+ */
+export async function exportTargetOf(
+  root: string,
+  subpath: string | undefined,
+): Promise<string | undefined> {
+  try {
+    const manifest = JSON.parse(await readFile(join(root, "package.json"), "utf8")) as {
+      exports?: Record<string, unknown>;
+      main?: string;
+      module?: string;
+    };
+    const key = subpath === undefined ? "." : `./${subpath}`;
+    // `exports` 的三种形状（都要认）：
+    // · 以 `.` 开头的键映射（标准）→ 取 `exports["."]` / `exports["./sub"]`；
+    // · **条件对象本身**（`{ development, default }`，`mdast-util-*` 就是这形状）→ 它**就是**根出口；
+    // · 没有 `exports` → 按 node 规则退回 `module` → `main`（老包如 `fortune-sheet`）。
+    const table = manifest.exports;
+    const isSubpathMap =
+      table !== undefined &&
+      Object.keys(table).some((name) => name === "." || name.startsWith("./"));
+    const entry =
+      (isSubpathMap ? table?.[key] : key === "." ? table : undefined) ??
+      (key === "." ? (manifest.module ?? manifest.main) : undefined);
+    const target =
+      typeof entry === "string"
+        ? entry
+        : entry === null || typeof entry !== "object"
+          ? undefined
+          : // 条件按**运行期**优先级挑：`import`（ESM 入口，`"type": "module"` 的包都走它）→
+            // `default` → `require`。`types` 是类型声明（`index.d.ts`），拿它去打包会得到 3460 个
+            // PARSE_ERROR——rolldown 把声明文件当 JS 解析，所以它只能垫底。
+            pickCondition(entry as Record<string, unknown>);
+    if (typeof target !== "string") return undefined;
+    return resolveInPackage({ name: "", version: "", root }, target.replace(/^\.\//u, ""));
+  } catch {
+    return undefined;
+  }
+}
+
+/** 包清单里我们用到的那些字段（其余原样留着，调用方按需读）。 */
+export interface PackageManifest {
+  name: string;
+  version: string;
+  /** `dsh.client` 声明：有它才是 client 行（上游 `client-modules` 的 roster 判据）。 */
+  dsh?: { client?: unknown };
+  exports?: Record<string, unknown>;
+  main?: string;
+  module?: string;
+}
+
+/** 读包清单。 */
+export async function manifestOf(root: string): Promise<PackageManifest | undefined> {
+  try {
+    const manifest = JSON.parse(
+      await readFile(join(root, "package.json"), "utf8"),
+    ) as Partial<PackageManifest>;
+    if (manifest.name === undefined) return undefined;
+    return { ...manifest, name: manifest.name, version: manifest.version ?? "0" };
+  } catch {
+    return undefined;
+  }
+}
+
+/** 向上找最近的包（软链已由 node 解析解开）：返回清单与包根。 */
+export async function owningPackageOf(file: string): Promise<PackageRoot | undefined> {
+  let directory = dirname(file);
+  while (directory !== dirname(directory)) {
+    const manifest = await manifestOf(directory);
+    if (manifest !== undefined) return { ...manifest, root: directory };
+    directory = dirname(directory);
+  }
+  return undefined;
+}
+
+/** 包根 + 包内路径 → 绝对路径；越出包根一律拒绝（寻址来自 URL，不能穿透到仓库别处）。 */
+export function resolveInPackage(pkg: PackageRoot, filepath: string): string | undefined {
+  const target = resolvePath(pkg.root, filepath);
+  const inside = relative(pkg.root, target);
+  return inside === "" || inside.startsWith("..") || inside.startsWith(sep) ? undefined : target;
+}
+
+/**
+ * 包内**物理路径**回退：清单的 `exports` 没覆盖这个子路径时，按约定位置找文件。
+ *
+ * 老包很常见：`picomatch` 没有 `exports`、只有 `main`，而 `picomatch/posix` 就是 `posix.js`；
+ * 只声明了部分子路径的包同理。寻址按 URL 来（`<pkg>@<version>/<子路径>.js`），所以这里按子路径找文件。
+ */
+export async function fileInPackage(root: string, subpath: string): Promise<string | undefined> {
+  const pkg = { name: "", version: "", root };
+  for (const candidate of [
+    subpath,
+    `${subpath}.js`,
+    `${subpath}.mjs`,
+    join(subpath, "index.js"),
+    join(subpath, "index.mjs"),
+    join(subpath, "index.ts"),
+  ]) {
+    const file = resolveInPackage(pkg, candidate);
+    if (
+      file !== undefined &&
+      (await readFile(file, "utf8").then(
+        () => true,
+        () => false,
+      ))
+    )
+      return file;
+  }
+  return undefined;
+}
+
+/** 一个 specifier 的寻址结果：包名、包内路径、以及它对应的 URL。 */
+export interface ResolvedSpecifier {
+  name: string;
+  filepath: string;
+  url: string;
+}
+
+/**
+ * 说明符里的包名：`@scope/name` 取两段、`name` 取一段。作用域包**没有子路径**时，
+ * `indexOf("/", slash + 1)` 会返回 -1——直接 `slice` 会削掉最后一个字符，这里显式判掉。
+ */
+export function packageNameOf(specifier: string): string {
+  if (!specifier.startsWith("@")) return specifier.split("/")[0] ?? specifier;
+  const slash = specifier.indexOf("/");
+  if (slash < 0) return specifier;
+  const second = specifier.indexOf("/", slash + 1);
+  return second < 0 ? specifier : specifier.slice(0, second);
+}
+
+/**
+ * 包根 → 它**浏览器面**的文件。
+ *
+ * @param root - 包根目录。
+ * @param subpath - 出口名（不含包名，如 `client`、`brand-font.css`）；省略表示包的根出口。
+ * @returns 该出口对应的文件；清单没这个出口、且约定路径也不存在时返回 undefined。
+ */
+export async function clientHalfOf(root: string, subpath?: string): Promise<string | undefined> {
+  const exists = async (file: string): Promise<boolean> =>
+    await readFile(file, "utf8").then(
+      () => true,
+      () => false,
+    );
+  if (subpath !== undefined) {
+    const byExports = await exportTargetOf(root, subpath);
+    if (byExports !== undefined) return byExports;
+    // 清单没覆盖的按物理路径试（`src/<subpath>/index.ts` 是 client 半的约定位置）。
+    const pkg = { name: "", version: "", root };
+    for (const candidate of [
+      join("src", subpath, "index.ts"),
+      join(subpath, "index.ts"),
+      subpath,
+    ]) {
+      const file = resolveInPackage(pkg, candidate);
+      if (file !== undefined && (await exists(file))) return file;
+    }
+    return undefined;
+  }
+  // 根出口：`dsh.client` 声明的包用它的 `./client`；其余用约定路径 `src/client/index.ts`。
+  const byClient = await exportTargetOf(root, "client");
+  if (byClient !== undefined) return byClient;
+  const conventional = join(root, "src", "client", "index.ts");
+  return (await exists(conventional)) ? conventional : undefined;
+}

package/src/serve-vite.ts

@@ -0,0 +1,211 @@
+/**
+ * dev 形态的客户端资源服务：**全权交给 vite**。
+ *
+ * 我们只提供两件它不知道的事：① 哪些包是 client 行、它们的源码入口在哪；② 页面 HTML 的骨架与自己那套
+ * 入口（`/plugins/.app/entry.js`）。其余（依赖预打包、CJS→ESM、具名导出、外置 require、共享 chunk、
+ * 内容 hash 缓存、HMR）都是 vite dev server 的现成能力——自己实现这些正是前面绕远路的地方。
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Context } from "@deepseek-ai/cordis";
+import { traceOf } from "./trace.ts";
+import { createServer, type ServerOptions, type ViteDevServer } from "vite";
+import { clientModulesAlias } from "./bundle.ts";
+import { dshClientRowsPlugin, ROWS_VIRTUAL } from "./vite-plugin.ts";
+import { packageRootOf } from "./resolve.ts";
+
+/**
+ * 行清单来源：cordis Loader 的 entries 里声明 `dsh.client` 的那些包。
+ *
+ * 只给**包名**——包的位置与 client 半的入口交给 vite 自己 resolve（插件里用 `this.resolve`）。
+ */
+export interface RowsSource {
+  /** 行清单：包名 → client 半的源文件（各 entry 用自己的 baseUrl 解析）。 */
+  rows: () => Promise<Map<string, string>>;
+}
+
+function rowsOf(source: RowsSource): Promise<Map<string, string>> {
+  return source.rows();
+}
+
+/** 起一个 vite dev server（middleware 模式），并把 `/plugins` 前缀下的请求交给它。 */
+/** vite 的 HMR WebSocket 路径：专有路径，避免与上游自身的 upgrade 路由抢。 */
+export const HMR_PATH = "/__dsh_hmr";
+
+/** vite 期望的 http server 类型（`server.hmr.server`）：HMR 的 WebSocket 挂在它的 `upgrade` 上。 */
+type HmrServer = NonNullable<
+  Extract<NonNullable<ServerOptions["hmr"]>, { server?: unknown }>["server"]
+>;
+
+export interface ViteHandoff {
+  /** 有没有挂 HMR（无端口形态没有同源的 http server 可挂，见 `hmr: false`）——页面决定要不要注入客户端。 */
+  hmr: boolean;
+  /** 把 `/plugins/*` 的请求交给 vite（返回 true 表示它接管了）。 */
+  serve: (req: IncomingMessage, res: ServerResponse) => boolean;
+  /** 让 vite 渲染一份 HTML（插件的 `transformIndexHtml` 会在这里注入入口 script）。 */
+  transformHtml: (html: string) => Promise<string>;
+}
+
+export async function startViteDev(
+  ctx: Context,
+  options: {
+    repoRoot: string;
+    base: string;
+    rows: RowsSource;
+    resolvePluginUrl: (url: string) => Promise<string | undefined>;
+    /** 裸说明符 → 联邦地址（三方与"非开发模块"都由它接管，见 `ClientRowsPluginOptions.depsUrl`）。 */
+    depsUrl: (specifier: string) => Promise<string | undefined>;
+    /** 宿主进程的 http server：HMR 的 WebSocket 要挂在它的 `upgrade` 上。 */
+    httpServer?: HmrServer | undefined;
+  },
+): Promise<ViteHandoff> {
+  const trace = traceOf(ctx, "vite");
+  const { repoRoot, base } = options;
+  /**
+   * 页面与入口所在的真实目录（vite 的 root）。
+   *
+   * 按**本包自己的位置**推，不从 `repoRoot` 拼：打包形态下 `repoRoot` 是 profile 目录
+   * （`$DSH_HOME/profiles/desktop`），从它拼出的 `packages/client/…/app-boot` 并不存在——vite 的 root
+   * 一空，`/index.html` 404、入口也转译不了，页面就只剩一具空壳。这条事实与 `index.ts` 的 `appRoot`
+   * 同源（那里也从包根推）。
+   */
+  const appRoot = fileURLToPath(new URL("../app-boot", import.meta.url));
+  /** 页面所在的端口（HMR 的 WebSocket 必须与页面**同源同端口**，否则客户端连不上）。 */
+  const pagePort = ((): number | undefined => {
+    const address = options.httpServer?.address();
+    if (address !== null && address !== undefined && typeof address === "object")
+      return address.port;
+    const fromEnv = process.env["PORT"];
+    return fromEnv === undefined ? undefined : Number(fromEnv);
+  })();
+  // **当前**实例：vite 自己 `restart()` 后会建一个新 server，插件的 `configureServer` 再回调过来。
+  // 不跟这个引用的话，重启之后路由还指着已关闭的旧实例（请求开始成片失败，宿主也可能因此退出）。
+  let current: ViteDevServer | undefined;
+  const server: ViteDevServer = await createServer({
+    // **root 收在 app-boot**：仓库里的源码都在 root 之外，vite 因此只能用 `/@fs/<绝对路径>` 引用它们
+    // ——URL 空间只剩 `@` 前缀（`@/…`、`@client-modules/…`、`/@fs/…`、`/@id/…`、`/@vite/…`），不会有
+    // 裸的 `/packages/…`、`/vendor/…` 混进来。页面与入口就是这个目录里的两个文件。
+    root: appRoot,
+    // 先让 vite 用**它自己的 URL 空间**（`/@vite`、`/@id`、`/@fs` 都在根上）；对外那层 `/plugins/...`
+    // 等页面跑起来再作为映射加回来。
+    //
+    // **不要**把 base 改成 `/@/` 去"统一前缀"：vite 会给所有不以 base 开头的绝对 URL 再补一层，
+    // 联邦地址（`/@client-modules/…`）会变成 `/@/@client-modules/…`，两条链全断。
+    base: "/",
+    // 浏览器没有 `process`：客户端半常读 `process.env.NODE_ENV`（上游 client 打包也做同样的替换）。
+    define: {
+      "process.env.NODE_ENV": JSON.stringify(process.env["NODE_ENV"] ?? "development"),
+      "process.env": "{ env: {} }",
+      // 裸 `process` 同样要给空壳（逐文件服务的源码里也会读它）。
+      process: "{ env: {} }",
+    },
+    publicDir: false,
+    // **不做 history fallback**（`spa` 会把没解析出来的路径静默回一份 index.html）：请求都在 `@` 前缀
+    // 的 URL 空间里（`@/…`、`@client-modules/…`、`/@fs/…`），谁没解析出来就该**当场 404**——否则浏览器
+    // 把 HTML 当模块执行，报出来的是一堆看不懂的错，而真正没命中的那个 URL 连线索都没有。
+    appType: "mpa",
+    // 依赖优化：**非开发模块**（`dsh.dev.exclude`）的入口交给 vite 预打包——一次构建、共享 chunk、
+    // 落盘 `<root>/node_modules/.vite/deps`、按内容 hash 失效；改着的包不在其中，仍逐文件走 vite（HMR）。
+    // 缓存目录用默认的 `node_modules/.vite`：跨进程、跨 profile 共用一份，不按进程隔离。
+    //
+    // **不用 vite 的 optimizeDeps**：客户端资源由我们自己的联邦链产出（`@client-modules/…`），vite 只管
+    // 页面与本地文件（`@/…`）。开着它会去预打包 workspace 源码，形成第二条链（浏览器里出现
+    // `node_modules/.vite/deps/@_packages_profile…` 就是这么来的）。
+    // **不读也不监听配置文件**：配置全是内联的（下面这些字段）。默认它会在 root 下找 `vite.config.*`
+    // 并 watch，改动就 `restart()` 自己——而这个 dev server 跑在 dsh 宿主进程里，重启会连带把整条
+    // 服务拖下水。关掉这条路径。
+    configFile: false,
+    resolve: {
+      // `@/…` → 仓库根、`node:*` → 求值安全的空替身（与联邦构建同一套约定，替身形态见 `node-stub.*`）。
+      alias: clientModulesAlias({ repoRoot, nodeStub: join(appRoot, "node-stub.ts") }),
+    },
+    server: {
+      middlewareMode: true,
+      // **关掉预转换**：vite 会对模块的静态 import 递归预热（`transformRequest`），而我们的联邦地址是
+      // **外部** URL（由自己的路由按请求预编译）——它照样去 load，于是日志里一串
+      // `Pre-transform error: Failed to load url /@client-modules/…`。预热换来的并行度不值得这份噪音。
+      preTransformRequests: false,
+      // HMR 的 WebSocket 挂到宿主的 http server 上：**路径专有**（避免与上游自身的 upgrade 路由抢），
+      // **端口与页面一致**（客户端连的就是页面这个端口）。调用方要先在 webServer 上注册同名 upgrade
+      // 路由——上游对未注册的升级请求会直接 destroy socket，vite 就握不上手。
+      ...(options.httpServer === undefined
+        ? {}
+        : {
+            hmr: {
+              server: options.httpServer,
+              path: HMR_PATH,
+              ...(pagePort === undefined ? {} : { clientPort: pagePort }),
+            },
+          }),
+      // 整个仓库都在 root 内，`/@fs/…` 的许可自然覆盖（vite 对 root 之外的文件会**放行**到 next，
+      // 表现为一串"没被 vite 接手"的 404）。
+      fs: { strict: false, allow: [repoRoot] },
+    },
+    // **不用** vite 的 `optimizeDeps`：裸说明符已由插件统一改写成 `@deps/`（我们自己预打包的产物），
+    // vite 再打一份就会与聚合产物里的那份形成两个实例。
+    // **不用** vite 的 `optimizeDeps`（关掉自动发现）：非开发模块与三方都由我们的联邦链产出，裸说明符
+    // 已在插件里改写成 `@client-modules/…`，这里没有任何东西需要预打包。开着只会多出第二条链（浏览器里
+    // 同时出现 `.vite/deps/react.js` 与我们的 `@client-modules/react@…/index.js`）与一次全仓扫描。
+    // **彻底不用** vite 的依赖优化器：裸说明符已由插件统一改写成 `@client-modules/…`（我们自己的联邦链产出），
+    // 这里没有任何东西需要它预打包。`noDiscovery: true` 只关了"自动发现"，扫描器仍会去解析那些包名——而行清单
+    // 是**虚拟模块**、里面写的包名 vite 按 `package.json` 的去向解析，落到工作区解析面上就报
+    // `Cannot find package … imported from …/package.json`（上游 workspace 内部包只存在于 vendor / 闭包）。
+    // `disabled` 是官方给的"整个关掉"（标了 deprecated，但语义正是这个）。
+    optimizeDeps: { disabled: true, noDiscovery: true, include: [] },
+    plugins: [
+      dshClientRowsPlugin({
+        repoRoot,
+        rows: () => rowsOf(options.rows),
+        resolvePluginUrl: options.resolvePluginUrl,
+        depsUrl: options.depsUrl,
+        onServer: (devServer) => {
+          current = devServer;
+        },
+      }),
+    ],
+  });
+  current = server;
+  ctx.logger.info("client-modules: vite dev server 就绪（root=%s）", repoRoot);
+  /** 页面入口（root=app-boot，所以就是 `/index.html`）。 */
+  const pageEntry = "/index.html";
+  const serve = (req: IncomingMessage, res: ServerResponse): boolean => {
+    if ((req.url ?? "").split("?")[0] === "/" || (req.url ?? "").split("?")[0] === "/index.html") {
+      req.url = pageEntry;
+    }
+    // `/plugins/*` 由 host 那层自己的路由先处理（那里挂的是对外形态的资源），其余全交给 vite——
+    // 它要服务的形态很多（虚拟模块 `/@id`、取文件 `/@fs`、预打包 `/node_modules/.vite/deps`、HMR
+    // 通道），白名单只会不断漏。
+    if ((req.url ?? "").startsWith(`${base}/`)) return false;
+    // 单次请求出错不该把宿主带走：vite 的 middlewares 里任何未捕获异常都只记一条 500。
+    try {
+      // 非 2xx 才留痕（正常请求不吵）：vite 没接住时能立刻看到是哪条 URL。
+      res.on("finish", () => {
+        if (res.statusCode < 400) return;
+        trace("%s %s → %s", req.method ?? "", req.url ?? "", res.statusCode);
+      });
+      (current ?? server).middlewares(req, res, () => {
+        // vite 没接住：留下线索（桌面形态经自定义协议进来，请求形态与 http 不同，这条日志能立刻定位）。
+        trace("miss %s %s", req.method ?? "", req.url ?? "");
+        if (!res.headersSent) res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+        if (!res.writableEnded) res.end("client-modules: vite 没有这条路由\n");
+      });
+    } catch (error) {
+      ctx.logger.error(error);
+      if (!res.headersSent) res.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
+      if (!res.writableEnded) res.end(`dev-client: vite 处理失败：${String(error)}\n`);
+    }
+    return true;
+  };
+  return {
+    serve,
+    transformHtml: async (html: string) => await server.transformIndexHtml(`${base}/`, html),
+    hmr: options.httpServer !== undefined,
+  };
+}
+
+/** 虚拟入口的浏览器 URL（HTML 里引用它）。 */
+export const ROWS_URL = `@id/__x00__${ROWS_VIRTUAL}`;
+
+/** 包根解析用（`packageRootOf` 在这里只用一次，便于将来换成 vite 的 resolver）。 */
+export { packageRootOf };

package/src/trace.ts

@@ -0,0 +1,25 @@
+import type { Context } from "@deepseek-ai/cordis";
+
+/**
+ * 诊断细节（逐包预编译、逐请求那一类）的具名 logger。
+ *
+ * 名字交给 logger（`ctx.logger(name)`）；**值走参数**、不拼进文本——cordis 的 logger 没有"每次调用带
+ * meta"这回事（`meta` 是 logger 实例级的），所以结构化的东西作为 `%o` 的参数传（exporter 拿到的
+ * `args` 里是结构与值，而不是一段 `key=value` 文本）。键名若出现，用 `.` 分层、不带空格。
+ *
+ * **是否调用**由本开关决定：运行时的日志门槛不由我们定（loader 注册的 exporter 允许 DEBUG），而这类细节
+ * 一次启动两千多行、每请求一行，默认不调，`DSH_TRACE=1` 时再调。出问题的几行走 `warn`。
+ * @param ctx - 这条链的上下文。
+ * @param name - 这个 logger 的名字（如 `federation` / `vite`）。
+ * @returns `(format, ...args)` 形态的诊断出口；开关没开时什么都不做。
+ */
+export function traceOf(
+  ctx: Context,
+  name: string,
+): (format: string, ...args: readonly unknown[]) => void {
+  if (process.env["DSH_TRACE"] !== "1") return () => {};
+  const logger = ctx.logger(name);
+  return (format: string, ...args: readonly unknown[]) => {
+    logger.debug(format, ...args);
+  };
+}