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

package/src/client/__tests__/modules-service.spec.ts

@@ -0,0 +1,43 @@
+// client 半只有一个职责：把上游 `modules` 服务补上。判据是"上游真正用到的那两个成员形状对"——
+// 上游 `ui-settings-general` 把 `entries.releaseChange` 当 `useSyncExternalStore` 的快照读、
+// 用 `entries.dismissRelease()` 关掉提示，动态插件运行器用 `invalidate()` 做模块失效。
+import { Context } from "@deepseek-ai/cordis";
+import { describe, expect, it } from "vitest";
+import { apply } from "../index.ts";
+
+interface ModulesService {
+  readonly entries: {
+    readonly releaseChange: {
+      getSnapshot: () => unknown;
+      subscribe: (listener: () => void) => () => void;
+    };
+    readonly dismissRelease: () => void;
+  };
+  readonly invalidate: (id: string) => void;
+}
+
+async function modulesOf(): Promise<ModulesService> {
+  const ctx = new Context();
+  await ctx.plugin({ apply });
+  return ctx.get("modules") as unknown as ModulesService;
+}
+
+describe("client 半的 modules 服务面", () => {
+  it("releaseChange 是恒 undefined 的可订阅快照（我们这条链没有跨 Host 版本的插件更新）", async () => {
+    const modules = await modulesOf();
+    expect(modules.entries.releaseChange.getSnapshot()).toBeUndefined();
+    const unsubscribe = modules.entries.releaseChange.subscribe(() => {});
+    expect(typeof unsubscribe).toBe("function");
+    unsubscribe();
+  });
+
+  it("dismissRelease 与 invalidate 可调用（提示已读与模块失效在本链上都是空操作）", async () => {
+    const modules = await modulesOf();
+    expect(() => {
+      modules.entries.dismissRelease();
+    }).not.toThrow();
+    expect(() => {
+      modules.invalidate("plugin-x");
+    }).not.toThrow();
+  });
+});

package/src/client/__tests__/terminal-recovery.spec.ts

@@ -0,0 +1,65 @@
+// 终端恢复兜底：宿主已经不认的终端 id（`closedIds` / 重启后消失）不能再拿来 `retain` —— 而侧栏布局与
+// 客户端 `bindings` 会一直把它带回来，`TerminalView` 的 `createWhenMissing` 因此恒为 false，面板永远停在
+// "此终端已不存在，请新建终端"。这里守的是"对账"这一步：清单里没有这个 id 就当新 tab（删 binding、丢掉
+// 旧视图），让上游按其本意分配一个新终端；清单里有则原样透传（恢复能力不变）。
+import { Context } from "@deepseek-ai/cordis";
+import { describe, expect, it } from "vitest";
+import { apply } from "../index.ts";
+
+interface Fake {
+  readonly service: unknown;
+  readonly bindings: Map<string, string>;
+  readonly views: Map<string, Map<string, unknown>>;
+}
+
+/** 上游 `ClientTerminals` 的最小替身：`view` 在**原型**上（我们的兜底改的就是原型）。 */
+function fakeTerminals(alive: boolean): Fake {
+  const bindings = new Map<string, string>([["s|content", "terminal-1"]]);
+  const inventories = new Map([["s", { items: new Map(alive ? [["terminal-1", {}]] : []) }]]);
+  const views = new Map([["s", new Map<string, unknown>([["key", {}]])]]);
+  class Terminals {
+    readonly bindings = {
+      get: (sessionId: string, contentId: string): string | undefined =>
+        bindings.get(`${sessionId}|${contentId}`),
+      delete: (sessionId: string, contentId: string): void => {
+        bindings.delete(`${sessionId}|${contentId}`);
+      },
+    };
+    readonly inventories = inventories;
+    readonly views = views;
+    view(...args: unknown[]): unknown {
+      return args;
+    }
+  }
+  return { service: new Terminals(), bindings, views };
+}
+
+async function loaded(fake: Fake): Promise<{ view: (...args: unknown[]) => unknown }> {
+  const ctx = new Context();
+  ctx.provide("webTerminals", fake.service as never);
+  await ctx.plugin({ apply });
+  return {
+    view: (...args: unknown[]) =>
+      (fake.service as { view: (...a: unknown[]) => unknown }).view(...args),
+  };
+}
+
+describe("终端恢复兜底", () => {
+  it("宿主已经不认这个 id 时：当新 tab——删 binding、丢掉旧视图、不把 id 传下去", async () => {
+    const fake = fakeTerminals(false);
+    const { view } = await loaded(fake);
+    const args = view("s", "key", "content", undefined, undefined);
+    expect(fake.bindings.has("s|content")).toBe(false);
+    expect(fake.views.get("s")?.has("key")).toBe(false);
+    expect(args).toEqual(["s", "key", "content", undefined, undefined]);
+  });
+
+  it("清单里还在时：原样透传（恢复能力不变）", async () => {
+    const fake = fakeTerminals(true);
+    const { view } = await loaded(fake);
+    const args = view("s", "key", "content", undefined, undefined);
+    expect(fake.bindings.has("s|content")).toBe(true);
+    expect(fake.views.get("s")?.has("key")).toBe(true);
+    expect(args).toEqual(["s", "key", "content", undefined, undefined]);
+  });
+});

package/src/client/index.ts

@@ -0,0 +1,101 @@
+// client 半：两件事，都是**把上游那条链缺的面补上**。
+//
+// 1. `modules` 服务面：上游 `ui-settings-general` 的 client 插件 inject 它（有它就忽略 peer），
+//    我们的装配停用了上游 `client-modules` 行，所以这里补一个最小实现（见文件头注释与 README）。
+// 2. 终端恢复兜底：上游 `api-terminal-controller` 的客户端把「侧栏 tab → 终端 id」记在 `bindings` 里
+//    （`dsh.terminal.binding.v1.[sessionId, contentId]`），而 Host 侧 `close()` 会把那个 id 记进
+//    `closedIds` 并且**永不再接受**（`retain()` 回 `terminal/unavailable`）。布局与 binding 会把这个
+//    已失效的 id 一直带回来，`TerminalView` 的 `createWhenMissing` 只在「没有 saved id」时才分配新终端
+//    —— 于是面板永远停在"此终端已不存在，请新建终端"，点"新建终端"复用的还是它。
+import type { Context } from "@deepseek-ai/cordis";
+
+/** 恒 `undefined` 的可订阅快照（`useSyncExternalStore` 的入参形状）。 */
+const NO_RELEASE_CHANGE = {
+  getSnapshot: (): undefined => undefined,
+  subscribe: () => () => {},
+};
+
+/**
+ * 浏览器侧的根插件。
+ *
+ * @param ctx - 浏览器侧根上下文。
+ */
+export function apply(ctx: Context): void {
+  ctx.reflect.provide("modules", {
+    entries: {
+      releaseChange: NO_RELEASE_CHANGE,
+      dismissRelease: () => {},
+    },
+    invalidate: () => {},
+  });
+  installTerminalRecovery(ctx);
+}
+
+/** 终端 id 与它在宿主清单里的存在性（清单未加载时按"不在"处理，见下面的取舍）。 */
+interface TerminalInventoryLike {
+  readonly items?: Map<string, unknown>;
+}
+interface TerminalsLike {
+  readonly bindings?: {
+    get?: (sessionId: string, contentId: string) => string | undefined;
+    delete?: (sessionId: string, contentId: string) => void;
+  };
+  readonly inventories?: Map<string, TerminalInventoryLike>;
+  readonly views?: Map<string, Map<string, unknown>>;
+}
+type ViewFn = (
+  sessionId: string,
+  key: string,
+  contentId: string,
+  terminalId?: string,
+  shellPath?: string,
+) => unknown;
+
+/**
+ * 终端恢复兜底：`view` 之前先**对账**，把宿主已经不认的终端 id 当新 tab 处理。
+ *
+ * 上游 `TerminalView` 的语义是「新 tab 才分配」（`createWhenMissing = saved === undefined`），而
+ * `saved = terminalId ?? bindings.get(sessionId, contentId)`：UI 传的 `terminalId` 实测是 `undefined`，
+ * 所以决定权全在 `bindings` —— 它不随宿主侧关闭状态失效。清单里没有这个 id（宿主重启过、或那个终端被
+ * 关过）时删掉这条 binding，让上游按新 tab 分配；清单里有则原样透传，恢复能力不变。清单**没加载**时按
+ * 「不在」处理：那时用户要的就是打开一个终端，让它重新分配比卡在死状态里强。
+ *
+ * 注意：`bindings` / `inventories` 是上游 Service 的私有字段，`view` 在其原型上（实例属性覆盖无效，
+ * 见 cordis 的 Service 代理）——所以这里改的是原型。这是**绕过上游缺陷**，等上游把 binding 与关闭状态
+ * 对上账就该删掉。
+ *
+ * @param ctx - 浏览器侧根上下文。
+ */
+function installTerminalRecovery(ctx: Context): void {
+  ctx.inject(["webTerminals"], (scope) => {
+    const terminals = scope.get("webTerminals") as TerminalsLike | undefined;
+    if (terminals === undefined) return;
+    const proto = Object.getPrototypeOf(terminals) as {
+      view?: ViewFn;
+      __terminalRecovery?: boolean;
+    };
+    if (proto.view === undefined || proto.__terminalRecovery === true) return;
+    proto.__terminalRecovery = true;
+    const original = proto.view;
+    proto.view = function (
+      this: TerminalsLike,
+      sessionId: string,
+      key: string,
+      contentId: string,
+      terminalId?: string,
+      shellPath?: string,
+    ) {
+      const bound = terminalId ?? this.bindings?.get?.(sessionId, contentId);
+      const alive =
+        bound === undefined || this.inventories?.get(sessionId)?.items?.has(bound) === true;
+      if (!alive) {
+        this.bindings?.delete?.(sessionId, contentId);
+        // 已存在的视图**不会**重新构造（`view()` 里只在没有它时才 new），而它的 `createWhenMissing` 早就是
+        // false 了——不丢掉它，清 binding 也没用。
+        this.views?.get(sessionId)?.delete(key);
+        return original.call(this, sessionId, key, contentId, undefined, shellPath);
+      }
+      return original.call(this, sessionId, key, contentId, terminalId, shellPath);
+    };
+  });
+}

package/src/config.ts

@@ -0,0 +1,70 @@
+/**
+ * dev 形态的分流配置：profile 的 `dsh.dev.exclude` 点名的包**不算开发模块**。
+ *
+ * 那些包（如 `@deepseek-ai/*`）在 dev 期间不打算改，于是不值得为它们付"逐文件请求"的代价——
+ * 走按包聚合（一个包一份产物、共享 chunk），换掉模块级 HMR；没被点名的包是正在改的，保持逐文件走 vite。
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+/** 一条 glob（只支持 `*`，够用）→ 正则。 */
+function globToRegExp(pattern: string): RegExp {
+  const escaped = pattern.replace(/[/\\^$+?.()|[\]{}]/gu, "\\$&").replaceAll("*", ".*");
+  return new RegExp(`^${escaped}$`);
+}
+
+/**
+ * 读 profile 的 `dsh.dev.exclude`。
+ *
+ * profile 根按这个顺序找：启动器给的 `DSH_DESKTOP_DEV_PROFILE_DIR`（桌面形态）；`DSH_HOME` 的父目录
+ * （它总是 `<profile>/.dsh-store`，web 形态也有）；当前目录。
+ *
+ * @returns 匹配"非开发模块"的正则表；**没配就是全部**（见函数末尾的说明）。
+ */
+/**
+ * 桌面形态（含 bundle）：**全部按非开发模块**处理。
+ *
+ * 它的页面跑在自定义协议下（`dsh-…://app/`），请求经壳的字节管道进来——每个逐文件请求都要走一趟这条路，
+ * 几百个源码模块叠起来就是"刷新一次卡几十秒"。桌面形态本来也不需要"改哪个包只看哪个包"的细粒度取舍：
+ * 全部按包预编译，改包时那一份重建 + 通知页面刷新（见壳的 ws 端点）。
+ */
+/**
+ * 是不是**开发形态**（`dshdev web` / `dshdev desktop`；打包产物不是）。
+ *
+ * `DSH_DEV_FORM` 由 `dshdev` 注入给宿主（壳起宿主时会过滤掉 `DSH_DESKTOP_*`，那些是 Electron 侧的元数据；
+ * web 形态没有壳，所以这条由 CLI 直接给）——值只说哪种形态，**有没有值**才是判据。这一判据**一个 home**：
+ * 预编译策略（本文件）与"这条链的根在哪"（`src/index.ts` 的 `repoRootOf`）都用它。
+ *
+ * @returns dev 形态为 true；bundle（打包产物）为 false。
+ */
+export function isDevForm(): boolean {
+  return process.env["DSH_DEV_FORM"] !== undefined;
+}
+
+export async function devExcluded(profileDir: string): Promise<RegExp[]> {
+  // **只有 dev 形态才谈"哪些包不打算改"**：`dsh.dev.exclude` 是 dev 的取舍（点名的包不值得付逐文件请求的
+  // 代价，走按包聚合），打包形态（含 `dshdev --prod` 那份解析面）没有"改哪个包"这回事——一律全部预编译。
+  if (!isDevForm()) return [/.*/u];
+  try {
+    const manifest = JSON.parse(await readFile(join(profileDir, "package.json"), "utf8")) as {
+      dsh?: { dev?: { exclude?: string[] } };
+    };
+    const patterns = (manifest.dsh?.dev?.exclude ?? []).map(globToRegExp);
+    if (patterns.length > 0) return patterns;
+  } catch {
+    // 读不到就算没配。
+  }
+  // **读不到配置就是"不打算改任何包"**：全部走按包预编译。这正是两种形态"完美复用同一条链"的地方。
+  return [/.*/u];
+}
+
+/**
+ * 该包是否走**聚合**（即"非开发模块"）。
+ *
+ * @param name - 包名。
+ * @param patterns - {@link devExcluded} 的结果。
+ * @returns 命中任一 glob 即为真。
+ */
+export function isAggregated(name: string, patterns: readonly RegExp[]): boolean {
+  return patterns.some((pattern) => pattern.test(name));
+}

package/src/dirs.ts

@@ -0,0 +1,97 @@
+// 「格」的定义：装配根 / 解析根 / 数据根，以及**由它们派生**的那些路径。
+//
+// 术语与两种形态的取值组合见 `../../../../devpackages/dshdev/.agents/GLOSSARY.md`。这里的规矩是：
+// **路径只在这里拼**——别处取名字（`storeDir()`、`profileManifest()`），不手写
+// `join(x, "node_modules", ".pnpm")` 这种串。那些串散在各处时，改一格要满仓找，且两种形态各错一次。
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CLIENT_MODULES_CACHE } from "./bundle.ts";
+import { isDevForm } from "./config.ts";
+import { workspaceRootOf } from "./resolve.ts";
+
+/** 本包自己的根（页面的骨架、`node-stub` 与依赖解析的兜底基准都从它推）。 */
+export function packageRoot(): string {
+  return dirname(fileURLToPath(new URL("../package.json", import.meta.url)));
+}
+
+/** 页面与入口所在的目录（vite 的 root）：本包的 `app-boot`。 */
+export function appBootDir(): string {
+  return join(packageRoot(), "app-boot");
+}
+
+/** 本包的清单（依赖解析的一个基准：这条链的运行期依赖声明在它里面）。 */
+export function packageManifestPath(): string {
+  return join(packageRoot(), "package.json");
+}
+
+/**
+ * 装配根（profileDir）：这份部署装配出来的那一格。
+ *
+ * dev 是工作区里的 app 目录（`dshdev` 给的 `DSH_DESKTOP_DEV_PROFILE_DIR`），bundle 是宿主进程的 cwd
+ * （壳把宿主的 cwd 设成 `<dataDir>/profiles/<name>`）。
+ *
+ * @returns 第一个带 `package.json` 的候选取值；都没有时退回 cwd。
+ */
+export async function profileDir(): Promise<string> {
+  const candidates = [process.env["DSH_DESKTOP_DEV_PROFILE_DIR"], process.cwd()].filter(
+    (value): value is string => value !== undefined && value !== "",
+  );
+  for (const candidate of candidates) {
+    if (
+      await readFile(join(candidate, "package.json"), "utf8").then(
+        () => true,
+        () => false,
+      )
+    ) {
+      return candidate;
+    }
+  }
+  return process.cwd();
+}
+
+/** 装配根的清单：`<profileDir>/package.json`（pnpm 从这里解析到装配行与工作区的包）。 */
+export async function profileManifestPath(): Promise<string> {
+  return join(await profileDir(), "package.json");
+}
+
+/**
+ * 解析根：依赖解析、watch、缓存的基准。
+ *
+ * dev 再向上找**工作区根**（`node_modules` 与 lockfile 在那儿）；bundle 的装配根本身就带自己的
+ * `node_modules`，就是它。
+ */
+export async function resolutionRoot(): Promise<string> {
+  resolutionRootPromise ??= (async () => {
+    const profile = await profileDir();
+    return isDevForm() ? ((await workspaceRootOf(profile)) ?? profile) : profile;
+  })();
+  return await resolutionRootPromise;
+}
+
+let resolutionRootPromise: Promise<string> | undefined;
+
+/**
+ * 数据根（`$DSH_HOME`）：会话、设置、附件、日志。
+ *
+ * dev 缺省是 `<装配根>/.dsh-store`（`dshdev` 会显式给值），bundle 由壳按 app 的 `dsh.desktop.dataDir`
+ * 解析后经环境传进来。
+ */
+export async function dataDir(): Promise<string> {
+  return process.env["DSH_HOME"] ?? join(await profileDir(), ".dsh-store");
+}
+
+/** 解析根的清单：`<解析根>/package.json`（依赖解析的另一个基准）。 */
+export async function resolutionManifestPath(): Promise<string> {
+  return join(await resolutionRoot(), "package.json");
+}
+
+/** pnpm 的虚拟 store：`<解析根>/node_modules/.pnpm`。 */
+export async function storeDir(): Promise<string> {
+  return join(await resolutionRoot(), "node_modules", ".pnpm");
+}
+
+/** 这条链自己的缓存目录（联邦产物与聚合结果，与 vite 的 `.vite` 并列）。 */
+export async function cacheDir(): Promise<string> {
+  return join(await resolutionRoot(), CLIENT_MODULES_CACHE);
+}