@morlay/dsh-desktop-shell 0.2.5 → 0.2.6

package/src/__tests__/shell-env.spec.ts

@@ -0,0 +1,131 @@
+import type { ChildProcess } from "node:child_process";
+import { access } from "node:fs/promises";
+import { afterEach, describe, expect, it } from "vitest";
+import { rcFileFor, shellQuote, shellWrappedSpawn } from "../shell-env.ts";
+
+const ORIGINAL_SHELL = process.env.SHELL;
+
+async function firstInstalled(candidates: readonly string[]): Promise<string | undefined> {
+  for (const candidate of candidates) {
+    try {
+      await access(candidate);
+      return candidate;
+    } catch {
+      // 不在这个 runner 上，试下一个
+    }
+  }
+  return undefined;
+}
+
+// 包装行为与具体 shell 无关，用 runner 上第一个带 rc 文件的 shell：CI（ubuntu-latest）没有 zsh。
+const RC_SHELL = await firstInstalled(["/bin/bash", "/usr/bin/bash", "/bin/zsh", "/usr/bin/zsh"]);
+
+function useRcShell(): string {
+  if (RC_SHELL === undefined) throw new Error("runner has no bash/zsh to wrap with");
+  process.env.SHELL = RC_SHELL;
+  return RC_SHELL;
+}
+
+interface Outcome {
+  readonly code: number | null;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+function runWrapped(
+  command: string,
+  args: readonly string[],
+  env: Record<string, string> = {},
+): Promise<Outcome> {
+  return new Promise<Outcome>((resolveOutcome, reject) => {
+    const child: ChildProcess = shellWrappedSpawn(command, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { ...process.env, ...env },
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString("utf8");
+    });
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString("utf8");
+    });
+    child.once("error", reject);
+    child.once("exit", (code) => {
+      resolveOutcome({ code, stdout, stderr });
+    });
+  });
+}
+
+afterEach(() => {
+  if (ORIGINAL_SHELL === undefined) delete process.env.SHELL;
+  else process.env.SHELL = ORIGINAL_SHELL;
+});
+
+describe("rcFileFor", () => {
+  it("maps bash and zsh to their rc files, by basename", () => {
+    expect(rcFileFor("bash")).toBe("~/.bashrc");
+    expect(rcFileFor("/bin/bash")).toBe("~/.bashrc");
+    expect(rcFileFor("/usr/local/bin/zsh")).toBe("~/.zshrc");
+  });
+
+  it("sources no rc file for other shells", () => {
+    expect(rcFileFor("/usr/bin/fish")).toBe("");
+    expect(rcFileFor("sh")).toBe("");
+    expect(rcFileFor("")).toBe("");
+  });
+});
+
+describe("shellQuote", () => {
+  it("single-quotes a value and escapes embedded quotes", () => {
+    expect(shellQuote("plain")).toBe("'plain'");
+    expect(shellQuote("")).toBe("''");
+    expect(shellQuote("a b")).toBe("'a b'");
+    expect(shellQuote("it's")).toBe("'it'\\''s'");
+  });
+});
+
+describe("shellWrappedSpawn", () => {
+  it("runs the command directly when no rc file applies", async () => {
+    delete process.env.SHELL;
+    const outcome = await runWrapped(process.execPath, ["-p", "process.env.DSH_MARK"], {
+      DSH_MARK: "direct",
+    });
+
+    expect(outcome.code).toBe(0);
+    expect(outcome.stdout.trim()).toBe("direct");
+  });
+
+  it.skipIf(process.platform === "win32")(
+    "runs the command through the login shell with quoted arguments intact",
+    async () => {
+      useRcShell();
+      const outcome = await runWrapped("/bin/echo", ["a b'c", "d"]);
+
+      expect(outcome.code).toBe(0);
+      expect(outcome.stdout.trimEnd()).toBe("a b'c d");
+    },
+  );
+
+  it.skipIf(process.platform === "win32")(
+    "keeps the command in the same process, so its status is the shell's status",
+    async () => {
+      useRcShell();
+      const outcome = await runWrapped("/bin/sh", ["-c", "exit 7"]);
+
+      expect(outcome.code).toBe(7);
+    },
+  );
+
+  it.skipIf(process.platform === "win32")(
+    "passes the environment through the wrapper without leaking rc output",
+    async () => {
+      const shell = useRcShell();
+      const outcome = await runWrapped(process.execPath, ["-p", "process.env.SHELL"]);
+
+      expect(outcome.code).toBe(0);
+      expect(outcome.stdout.trim()).toBe(shell);
+      expect(outcome.stderr).toBe("");
+    },
+  );
+});

package/src/__tests__/shell-import-boundary.spec.ts

@@ -0,0 +1,69 @@
+// 壳产物的依赖边界：`app.asar` 里只有壳自己的字节（`@local/*`、`@morlay/dsh-desktop-host`
+// 与配置里 `inline` 的上游包内联进来）。壳入口可达的模块图里**不允许**出现「既不在内联列表、
+// 又解析不到」的裸引用——它们能过类型检查、能打出裸 `import`，但装进 `app.asar` 后只在真机
+// 启动时炸。
+//
+// 这条边界是构建配置（`tsdown.config.ts` 的 `deps` / `inline`）与源码的共同事实，因此在这里守：
+// 从壳入口出发沿相对 import 遍历，收集每个裸说明符，逐个核对白名单。
+import { readFile } from "node:fs/promises";
+import { dirname, relative, resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+
+const ROOT = resolve(import.meta.dirname, "..", "..");
+
+// 装进 `app.asar` 的入口：壳主进程与 preload。
+const SHELL_ENTRIES = ["src/index.ts", "src/preload-app.ts"];
+
+// 壳产物里能解析到的裸说明符：node 内建、Electron 自带、内联进来的本地包，
+// 以及 tsdown 配置里 `inline` 的那几个上游包（快捷键桥的设备偏好与原子写）。
+const ALLOWED = [
+  /^node:/u,
+  /^electron$/u,
+  /^@local\//u,
+  /^@morlay\/dsh-desktop-host(?:\/|$)/u,
+  /^@deepseek-ai\/dsh-client-shortcuts(?:\/|$)/u,
+  /^@deepseek-ai\/dsh-atomic-write(?:\/|$)/u,
+  /^@deepseek-ai\/dsh-util-values(?:\/|$)/u,
+  /^@deepseek-ai\/dsh-util-crypto(?:\/|$)/u,
+];
+
+// Type-only import 不留运行时字节，不在这条边界里。
+function withoutTypeImports(text: string): string {
+  return text.replace(/(?:^|\n)\s*import\s+type[\s\S]*?from\s*["'][^"']+["']/gu, "\n");
+}
+
+function specifiersOf(text: string): string[] {
+  const source = withoutTypeImports(text);
+  const found: string[] = [];
+  const from = /(?:^|\n)\s*(?:import|export)[\s\S]*?from\s*["']([^"']+)["']/gu;
+  const sideEffect = /(?:^|\n)\s*import\s*["']([^"']+)["']/gu;
+  const dynamic = /\bimport\(\s*["']([^"']+)["']\s*\)/gu;
+  for (const pattern of [from, sideEffect, dynamic]) {
+    for (const match of source.matchAll(pattern)) found.push(match[1] ?? "");
+  }
+  return found.filter((specifier) => specifier !== "");
+}
+
+describe("shell bundle dependency boundary", () => {
+  it("keeps the shell's module graph free of packages app.asar cannot resolve", async () => {
+    const visited = new Set<string>();
+    const offenders: string[] = [];
+    const queue = SHELL_ENTRIES.map((entry) => resolve(ROOT, entry));
+
+    while (queue.length > 0) {
+      const file = queue.pop() as string;
+      if (visited.has(file)) continue;
+      visited.add(file);
+      for (const specifier of specifiersOf(await readFile(file, "utf8"))) {
+        if (specifier.startsWith(".")) {
+          queue.push(resolve(dirname(file), specifier));
+          continue;
+        }
+        if (ALLOWED.some((pattern) => pattern.test(specifier))) continue;
+        offenders.push(`${relative(ROOT, file)} → ${specifier}`);
+      }
+    }
+
+    expect(offenders).toEqual([]);
+  });
+});

package/src/__tests__/stream-uplink.spec.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import { createStreamUplink } from "../stream-uplink.ts";
+
+function harness(): { uplink: ReturnType<typeof createStreamUplink>; log: string[] } {
+  const log: string[] = [];
+  const uplink = createStreamUplink(
+    (streamId, item) => {
+      log.push(`send ${String(streamId)} ${JSON.stringify(item)}`);
+    },
+    (streamId) => {
+      log.push(`end ${String(streamId)}`);
+    },
+  );
+  return { uplink, log };
+}
+
+describe("页面侧流的上行通道", () => {
+  it("id 未到时先排队，绑定后按序发出", () => {
+    const { uplink, log } = harness();
+    uplink.push({ typed: "a" });
+    uplink.push({ typed: "b" });
+    expect(log).toEqual([]);
+    uplink.bind(7);
+    expect(log).toEqual(['send 7 {"typed":"a"}', 'send 7 {"typed":"b"}']);
+    uplink.push({ typed: "c" });
+    expect(log.at(-1)).toBe('send 7 {"typed":"c"}');
+    expect(log.some((line) => line.startsWith("end"))).toBe(false);
+  });
+
+  it("上行结束时先交完排队项再收尾", () => {
+    const { uplink, log } = harness();
+    uplink.push({ typed: "a" });
+    uplink.close();
+    uplink.push({ typed: "late" });
+    uplink.bind(3);
+    expect(log).toEqual(['send 3 {"typed":"a"}', "end 3"]);
+  });
+
+  it("绑定后结束直接收尾，重复绑定报错", () => {
+    const { uplink, log } = harness();
+    uplink.bind(5);
+    uplink.close();
+    uplink.close();
+    expect(log).toEqual(["end 5"]);
+    expect(() => {
+      uplink.bind(6);
+    }).toThrow(/already bound/u);
+  });
+});

package/src/appconfig.ts

@@ -0,0 +1,79 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export const PROFILE_NAME = "desktop";
+
+// profile 自己的 patch 文档名（与上游 `PROFILE_PATCH_FILENAME` 同值）。不 import 上游常量：
+// `seed.ts` 进 `app.asar`，那里解析不到 `@deepseek-ai/*`。
+export const PROFILE_PATCH_NAME = "cordis.patch.yml";
+
+export interface AppWindowConfig {
+  readonly width: number;
+  readonly height: number;
+  readonly minWidth: number;
+  readonly minHeight: number;
+}
+
+export interface AppConfig {
+  readonly name: string;
+  readonly displayName: string;
+  readonly id: string;
+  readonly version: string;
+  readonly profile: typeof PROFILE_NAME;
+
+  readonly dataDir: string;
+  readonly window: AppWindowConfig;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function windowConfig(value: unknown): AppWindowConfig {
+  const record = isRecord(value) ? value : {};
+  return {
+    width: numberOr(record.width, 1280),
+    height: numberOr(record.height, 800),
+    minWidth: numberOr(record.minWidth, 800),
+    minHeight: numberOr(record.minHeight, 600),
+  };
+}
+
+function numberOr(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
+export async function loadAppConfig(exeDir: string): Promise<AppConfig> {
+  const path = join(exeDir, "appconfig.json");
+  const value: unknown = JSON.parse(await readFile(path, "utf8"));
+  if (
+    !isRecord(value) ||
+    typeof value.name !== "string" ||
+    value.name === "" ||
+    typeof value.displayName !== "string" ||
+    value.displayName === "" ||
+    typeof value.id !== "string" ||
+    value.id === "" ||
+    typeof value.version !== "string" ||
+    value.version === "" ||
+    value.profile !== PROFILE_NAME ||
+    (value.dataDir !== "xdg" && value.dataDir !== "env" && typeof value.dataDir !== "string")
+  ) {
+    throw new Error(`dsh desktop: invalid shell configuration ${path}`);
+  }
+  return {
+    name: value.name,
+    displayName: value.displayName,
+    id: value.id,
+    version: value.version,
+    profile: PROFILE_NAME,
+    dataDir: value.dataDir,
+    window: windowConfig(value.window),
+  };
+}
+
+export async function writeAppConfig(exeDir: string, config: AppConfig): Promise<void> {
+  await writeFile(join(exeDir, "appconfig.json"), `${JSON.stringify(config, undefined, 2)}\n`, {
+    mode: 0o600,
+  });
+}

package/src/developer-endpoint.ts

@@ -0,0 +1,30 @@
+// 后端调试的前端地址：这份 DevTools 前端由桌面 host 自己托管（`@morlay/dsh-desktop-host` 的
+// `/node-devtools` 前缀，产物取自上游 `@deepseek-ai/dsh-experimental-inspector` 的 `lib/devtools`）——
+// 它按 `ws` 查询参数连端点（值形如 `host:port/path`，前端自己补 `ws://`），连的是 host 回报的
+// Node inspector，而不是上游那条跨 realm 的同源路由（决策见
+// [ADR 桌面档调试面用 Node inspector](../../.agents/adrs/20261008-桌面档调试面用Node-inspector而非跨realm面板.md)）。
+
+import { DEVTOOLS_ASSETS_PREFIX } from "@morlay/dsh-desktop-host/paths";
+
+/** DevTools 前端在托管前缀下的入口路径（与上游底部面板用的是同一份产物）。 */
+const DEVTOOLS_ENTRY = "devtools_app.html";
+
+/**
+ * 把 host 回报的调试端点拼成应用 origin 下的 DevTools 入口。
+ * @param scheme - 应用自定义协议（壳派生自 app 名）。
+ * @param endpoint - host 回报的 WebSocket 端点（`ws://127.0.0.1:<port>/<uuid>`）。
+ * @returns 可在窗口里加载的入口 URL。
+ * @throws 端点不是 WebSocket 端点，或它的值不能原样进查询串。
+ */
+export function nodeInspectorDevtoolsUrl(scheme: string, endpoint: string): string {
+  const target = new URL(endpoint);
+  if (target.protocol !== "ws:" && target.protocol !== "wss:")
+    throw new Error(`dsh desktop: the inspector endpoint is not a WebSocket url: ${endpoint}`);
+  if (target.search !== "")
+    throw new Error(`dsh desktop: the inspector endpoint must not carry a query: ${endpoint}`);
+  // 不转义：`:` 与 `/` 在查询值里合法，且这样无论前端做不做解码都拿到同一份地址。
+  const socket = `${target.host}${target.pathname}`;
+  if (!/^[\u0021-\u007e]+$/u.test(socket) || socket.includes("&") || socket.includes("#"))
+    throw new Error(`dsh desktop: the inspector endpoint is not usable in a query: ${endpoint}`);
+  return `${scheme}://app${DEVTOOLS_ASSETS_PREFIX}/${DEVTOOLS_ENTRY}?ws=${socket}&panel=console&disableLocaleInfoBar=true`;
+}

package/src/developer-menu.ts

@@ -0,0 +1,198 @@
+// 壳的「后端调试」面：把 host 运行时开的 Node inspector 端点接到一个独立的 DevTools 窗口上。
+// 为什么是 Node inspector 而不是上游那套跨 realm 面板，见
+// [ADR 桌面档调试面用 Node inspector](../../.agents/adrs/20261008-桌面档调试面用Node-inspector而非跨realm面板.md)。
+
+import { BrowserWindow, Menu, MenuItem, dialog } from "./electron.ts";
+import type {
+  BrowserWindow as BrowserWindowType,
+  Menu as MenuType,
+  MenuItem as MenuItemType,
+  MenuItemConstructorOptions,
+} from "electron";
+import { nodeInspectorDevtoolsUrl } from "./developer-endpoint.ts";
+
+// 后端调试面要的 host 面（`DesktopHostProcess` 的结构子集）：命令 + 端点状态订阅。
+export interface DeveloperHostProcess {
+  inspect(port?: number): void;
+  endInspect(): void;
+  onInspected(listener: (state: { url: string | null; message?: string }) => void): () => void;
+}
+
+export interface DeveloperMenuOptions {
+  // 应用自定义协议（壳派生自 app 名）。
+  readonly scheme: string;
+  readonly appName: string;
+  // 后端进程还没起来时返回 undefined——菜单仍然可用，点了给提示。
+  readonly host: () => DeveloperHostProcess | undefined;
+  // 对话框的父窗口。
+  readonly mainWindow: () => BrowserWindowType | undefined;
+}
+
+function reportFailure(options: DeveloperMenuOptions, title: string, detail: string): void {
+  // 开发菜单是壳里的调试面（dev 形态才出现）：失败信息走终端，不进 shell.log。
+  console.error(`[dsh-shell] ${title}: ${detail}`);
+  const parent = options.mainWindow();
+  if (parent === undefined || parent.isDestroyed()) dialog.showErrorBox(title, detail);
+  else void dialog.showMessageBox(parent, { type: "error", message: title, detail });
+}
+
+// 往应用菜单的 View 子菜单里插两项（分隔符 + 调试项）；现有菜单没有 View 时返回 false。
+function insertIntoViewMenu(menu: MenuType | null, toggle: MenuItemConstructorOptions): boolean {
+  const view = menu?.items.find((entry) => entry.role === "viewMenu")?.submenu;
+  if (view === undefined) return false;
+  const devtools = view.items.findIndex((entry) => entry.role === "toggleDevTools");
+  const at = devtools === -1 ? view.items.length : devtools + 1;
+  view.insert(at, new MenuItem({ type: "separator" }));
+  view.insert(at + 1, new MenuItem(toggle));
+  return true;
+}
+
+// 现有菜单不可用时的兜底：只摆桌面应用该有的几项。macOS 的 app 菜单与 window 菜单不能省，
+// 少了它们 Cmd+Q / Cmd+W 这类系统快捷键会失效。
+function buildFallbackMenu(toggle: MenuItemConstructorOptions): MenuType {
+  const template: MenuItemConstructorOptions[] = [
+    ...(process.platform === "darwin" ? [{ role: "appMenu" } as const] : []),
+    { role: "fileMenu" },
+    { role: "editMenu" },
+    {
+      label: "View",
+      submenu: [
+        { role: "reload" },
+        { role: "forceReload" },
+        { role: "toggleDevTools" },
+        { type: "separator" },
+        toggle,
+        { type: "separator" },
+        { role: "resetZoom" },
+        { role: "zoomIn" },
+        { role: "zoomOut" },
+        { type: "separator" },
+        { role: "togglefullscreen" },
+      ],
+    },
+    { role: "windowMenu" },
+  ];
+  return Menu.buildFromTemplate(template);
+}
+
+/**
+ * 把「后端调试（Node Inspector）」挂进应用菜单的 View 里，并管理它那个 DevTools 窗口。
+ * 勾选 ⇔ 端点开着 ⇔ 窗口在：关窗口、取消勾选、host 回报端点没了，三条都收敛到同一状态。
+ * @param options - 协议、app 名与 host 取值函数。
+ * @returns 退订与收尾。
+ */
+export function installDeveloperMenu(options: DeveloperMenuOptions): { dispose(): void } {
+  let window: BrowserWindowType | undefined;
+  // 我们自己关窗口时置位：那一刻别再当成「用户关掉调试」。
+  let closingWindow = false;
+  let releaseInspected: (() => void) | undefined;
+  // 菜单项实例只有挂上之后才有，勾选状态一律经它同步（模板对象里拿不到实例）。
+  let toggleItem: MenuItemType | undefined;
+  const setChecked = (checked: boolean): void => {
+    if (toggleItem !== undefined) toggleItem.checked = checked;
+  };
+
+  function closeWindow(): void {
+    const current = window;
+    window = undefined;
+    if (current === undefined || current.isDestroyed()) return;
+    // 标志由 `closed` 处理器消费：`close()` 之后 `closed` 是另派发的，不能在这里复位。
+    closingWindow = true;
+    current.close();
+  }
+
+  // 收掉这次调试：订阅、窗口、host 端点一起消失（重复调用是幂等的）。
+  function closeInspectorHost(): void {
+    releaseInspected?.();
+    releaseInspected = undefined;
+    closeWindow();
+    try {
+      options.host()?.endInspect();
+    } catch (error) {
+      console.error("[dsh-shell] host inspector shutdown failed", error);
+    }
+  }
+
+  function openWindow(endpoint: string): void {
+    const current = window;
+    if (current !== undefined && !current.isDestroyed()) {
+      current.focus();
+      return;
+    }
+    let target: string;
+    try {
+      target = nodeInspectorDevtoolsUrl(options.scheme, endpoint);
+    } catch (error) {
+      setChecked(false);
+      releaseInspected?.();
+      releaseInspected = undefined;
+      reportFailure(options, "后端调试", error instanceof Error ? error.message : String(error));
+      return;
+    }
+    const created = new BrowserWindow({
+      width: 1_280,
+      height: 820,
+      title: `${options.appName} · Node Inspector`,
+      backgroundColor: "#202124",
+    });
+    window = created;
+    created.on("closed", () => {
+      if (window === created) window = undefined;
+      // 标志是一次性的：无论谁关的，用过就复位。
+      const closingOurselves = closingWindow;
+      closingWindow = false;
+      if (closingOurselves) return;
+      // 用户关掉窗口就等于关掉这次调试：勾选、端点、窗口收敛到「没开」。
+      closeInspectorHost();
+      setChecked(false);
+    });
+    void created.loadURL(target);
+  }
+
+  const toggle: MenuItemConstructorOptions = {
+    id: "desktop-host-inspector",
+    label: "后端调试（Node Inspector）",
+    type: "checkbox",
+    checked: false,
+    click: (menu) => {
+      toggleItem = menu;
+      if (!menu.checked) {
+        closeInspectorHost();
+        return;
+      }
+      const host = options.host();
+      if (host === undefined) {
+        setChecked(false);
+        reportFailure(options, "后端调试", "后端进程还没就绪，稍后再试。");
+        return;
+      }
+      releaseInspected?.();
+      releaseInspected = host.onInspected((state) => {
+        if (state.url !== null) {
+          openWindow(state.url);
+          return;
+        }
+        setChecked(false);
+        closeWindow();
+        if (state.message !== undefined)
+          reportFailure(options, "后端调试端点没有开起来", state.message);
+      });
+      try {
+        // 端口交给 host 挑（0 = 随机），壳不猜；已有端点（dev 的 `--inspect`）由 host 复用。
+        host.inspect(0);
+      } catch (error) {
+        releaseInspected?.();
+        releaseInspected = undefined;
+        setChecked(false);
+        reportFailure(options, "后端调试", error instanceof Error ? error.message : String(error));
+      }
+    },
+  };
+
+  // 默认菜单不一定就绪（真机上 `Menu.getApplicationMenu()` 可能是 null）：能插就插，
+  // 插不进去就自建一套——调试面不该因为菜单形态缺失而整个不可用。
+  if (!insertIntoViewMenu(Menu.getApplicationMenu(), toggle))
+    Menu.setApplicationMenu(buildFallbackMenu(toggle));
+
+  return { dispose: closeInspectorHost };
+}

package/src/directory-picker.ts

@@ -0,0 +1,37 @@
+import { dialog, ipcMain } from "./electron.ts";
+import type { BrowserWindow as BrowserWindowType } from "electron";
+import { DESKTOP_IPC, assertDesktopSender } from "./ipc.ts";
+
+export function installDesktopDirectoryPicker(
+  getWindow: () => BrowserWindowType | undefined,
+  scheme: string,
+): void {
+  const pending = new WeakMap<BrowserWindowType, Promise<string | null>>();
+  ipcMain.handle(DESKTOP_IPC.directoryPick, async (event) => {
+    const window = getWindow();
+    if (
+      window === undefined ||
+      window.isDestroyed() ||
+      event.sender !== window.webContents ||
+      event.senderFrame !== window.webContents.mainFrame
+    ) {
+      throw new Error("dsh desktop: rejected directory picker from an unowned renderer");
+    }
+    assertDesktopSender(event, scheme, ["app"]);
+    const existing = pending.get(window);
+    if (existing !== undefined) return existing;
+    if (window.isMinimized()) window.restore();
+    window.show();
+    window.focus();
+    const result = dialog
+      .showOpenDialog(window, { properties: ["openDirectory", "createDirectory"] })
+      .then(({ canceled, filePaths }) =>
+        window.isDestroyed() || canceled ? null : (filePaths[0] ?? null),
+      )
+      .finally(() => {
+        pending.delete(window);
+      });
+    pending.set(window, result);
+    return result;
+  });
+}

package/src/document-marks.ts

@@ -0,0 +1,58 @@
+// 桌面文档标记：客户端按这些属性切换窗口布局（macOS 交通灯内嵌、Windows 自绘 caption）。
+
+// Windows 标题栏高度（DIP），与窗口 `titleBarOverlay.height` 一致。
+export const WINDOWS_TITLEBAR_HEIGHT = 40;
+
+// Web UI 写入的主题来源属性。
+const THEME_SOURCE_ATTRIBUTE = "data-ds-theme-source";
+
+function whenRootReady(root: Document, run: () => void): void {
+  // preload 可能早于文档根存在。
+  if ((root.documentElement as HTMLElement | null) === null)
+    root.defaultView?.addEventListener("DOMContentLoaded", run, { once: true });
+  else run();
+}
+
+// 标记页面平台：macOS 布局（侧边栏顶部拖拽条与 logo 下沉）据此启用。
+export function markDocumentPlatform(platform: NodeJS.Platform, root: Document): void {
+  whenRootReady(root, () => {
+    root.documentElement.dataset.platform = platform;
+  });
+}
+
+// Windows 自绘 caption 标记：布局据此留出标题栏高度、把控制按钮位置让开。
+export function markWindowsTitlebar(platform: NodeJS.Platform, root: Document): void {
+  if (platform !== "win32") return;
+  whenRootReady(root, () => {
+    root.documentElement.dataset.windowsTitlebar = "";
+    root.documentElement.style.setProperty(
+      "--dsh-windows-titlebar-height",
+      `${String(WINDOWS_TITLEBAR_HEIGHT)}px`,
+    );
+  });
+}
+
+// macOS：把主题来源转发给主进程，窗口 vibrancy 才会跟随应用配色。
+export function syncNativeTheme(
+  platform: NodeJS.Platform,
+  root: Document,
+  send: (source: string) => void,
+): void {
+  if (platform !== "darwin") return;
+  let sent: string | undefined;
+  const publish = (): void => {
+    const value = root.documentElement.getAttribute(THEME_SOURCE_ATTRIBUTE);
+    if (value === null || value === sent) return;
+    sent = value;
+    send(value);
+  };
+  const observe = (): void => {
+    new MutationObserver(publish).observe(root.documentElement, {
+      attributeFilter: [THEME_SOURCE_ATTRIBUTE],
+    });
+    publish();
+  };
+  if (root.readyState === "loading")
+    root.defaultView?.addEventListener("DOMContentLoaded", observe, { once: true });
+  else observe();
+}

package/src/dshhome.ts

@@ -0,0 +1,29 @@
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import type { AppConfig } from "./appconfig.ts";
+
+export function xdgDataHome(): string {
+  if (process.platform === "darwin") return join(homedir(), "Library", "Application Support");
+  const configured = process.env.XDG_DATA_HOME;
+  if (configured !== undefined && configured.trim() !== "") return resolve(configured);
+  return join(homedir(), ".local", "share");
+}
+
+// 解析 `dataDir` 的三态：`xdg`（平台数据目录 + app 名）、`env`（交给环境，这里没有具体路径）、
+// 绝对路径。打包壳与 dev CLI（`--data-dir`）共用这一份，措辞与校验只写在这里。
+export function resolveConfiguredHome(name: string, spec: string): string | undefined {
+  if (spec === "env") return undefined;
+  if (spec === "xdg") return join(xdgDataHome(), name);
+  if (!isAbsolute(spec)) {
+    throw new Error(
+      `dsh desktop: dataDir must be xdg, env, or an absolute path, got ${JSON.stringify(spec)}`,
+    );
+  }
+  return spec;
+}
+
+export function resolveDshHome(config: AppConfig): string | undefined {
+  const override = process.env.DSH_APP_DSH_HOME;
+  if (override !== undefined && override.trim() !== "") return resolve(override);
+  return resolveConfiguredHome(config.name, config.dataDir);
+}